Getting Started with vFabric tc Server 2.5

Alex EvangSoftware and s/w Development

Aug 30, 2011 (5 years and 9 months ago)

1,556 views

This section provides quick start instructions for installing VMware vFabric™ tc Server™ Standard Edition and the VMware vFabric Hyperic® management components (HQ Server and Agent) on the same computer, creating a tc Runtime instance, and starting all components. The instructions install the tc Runtime component in a separate directory from the HQ management components.

Getting Started with vFabric tc Server
vFabric tc Server 2.5
Table of Contents
1.Copyright Notice...............................................................................................................1
2.Quick Start Instructions....................................................................................................3
3.Overview of tc Server.......................................................................................................7
3.1.Features of tc Server..............................................................................................7
3.2.Comparing tc Runtime and Apache Tomcat..........................................................9
3.3.tc Server Editions.................................................................................................14
3.4.How tc Server and Hyperic Work Together........................................................16
3.5.Links to Additional Documentation.....................................................................19
4.Release Notes..................................................................................................................21
4.1.Versioning Process...............................................................................................21
4.2.What's New and Changed in This Release?.........................................................21
4.3.Supported and Tested Configurations..................................................................22
4.4.Fixed Issues..........................................................................................................24
4.5.Restrictions..........................................................................................................25
5.What Are the Main Steps Required to Get Going?.........................................................27
5.1.Before You Begin................................................................................................27
5.2.Installing tc Server and Creating a New tc Runtime Instance.............................28
5.3.Starting the Components and Doing Initial Configuration..................................28
5.4.Exploring the Features of tc Server.....................................................................29
6.Installing tc Server..........................................................................................................31
6.1.Before You Begin:SystemRequirements...........................................................31
6.2.Installing tc Server:Main Steps...........................................................................33
6.3.Overview of tc Server Directories,Variables,and Configuration Files..............39
7.Post-Installation Tasks....................................................................................................45
7.1.Creating a New tc Runtime Instance...................................................................45
7.2.Starting and Stopping tc Runtime Instances........................................................63
7.3.Windows:Installing the HQ Server and Agents as Windows Services...............72
7.4.Starting and Stopping the HQ Server and Agents...............................................74
7.5.Getting Started with the HQ User Interface.........................................................77
7.6.Deploying Applications to tc Runtime Instances.................................................83
7.7.Uninstalling tc Server:Typical Steps..................................................................86
8.Upgrade and Migration Guide........................................................................................89
8.1.Upgrading a 2.0.X or 2.1.X tc Server Installation to 2.5.....................................89
8.2.Upgrading a 2.5.X tc Runtime to the Latest Version...........................................90
9.Tutorial:Using HQ to Configure and Manage tc Runtime Instances.............................95
9.1.Before You Begin................................................................................................95
9.2.Restart a tc Runtime Instance..............................................................................96
9.3.Reconfigure a tc Runtime Instance......................................................................97
9.4.Deploy a Web Application to a tc Server Runtime Instance.............................102
9.5.Add tc Runtime Instances to the Favorite Resources Portlet.............................105
vFabric tc Server 2.5 iii
9.6.Create an HQ Group of Multiple tc Runtime Instances.....................................106
9.7.Monitoring tc Runtime Instances.......................................................................109
9.8.Manage the Preconfigured Deadlock Detected Alert........................................110
10.Tutorial:Very Simple HelloWorld Web Application.................................................113
10.1.Before You Begin............................................................................................113
10.2.Creating and Deploying the HelloWorld Web Application.............................113
10.3.Java Source of the Hello.java Servlet..............................................................116
10.4.JSP Source for the hello.jsp JSP......................................................................118
10.5.Sample web.xml File.......................................................................................119
10.6.Sample Default index.html File.......................................................................119
10.7.Ant Build File to Compile and Package the Example.....................................120
11.Troubleshooting..........................................................................................................123
11.1.HQ:Resources Not Showing up in the HQ User Interface.............................123
11.2.HQ:Errors When Trying to Add an Auto-Discovered Resource....................124
11.3.HQ Agent:Errors When Starting on Solaris....................................................124
11.4.tc Runtime:Hot Redeploy/Stop/Undeploy on Windows Fails........................125
11.5.tc Runtime:Error When Running a Web Application on tc Runtime and Using
SpringSource Tool Suite...........................................................................................126
11.6.tc Runtime:JVMPerforming a Full GC..........................................................126
iv Getting Started
1.Copyright Notice
Copyright ©2011 VMware,Inc.All rights reserved.This product is protected by U.S.and
international copyright and intellectual property laws.VMware products are covered by one or
more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware,Inc.in the United States and/or
other jurisdictions.All other marks and names mentioned herein may be trademarks of their
respective companies.
Copyright Notice 1
vFabric tc Server 2.5 1
2 Getting Started
2 Copyright Notice
2.Quick Start Instructions
This section provides quick start instructions for installing VMware vFabric™tc Server™
Standard Edition and the VMware vFabric Hyperic® management components (HQ Server and
Agent) on the same computer,creating a tc Runtime instance,and starting all components.The
instructions install the tc Runtime component in a separate directory fromthe HQ management
components.
Note:tc Runtime is the runtime component of tc Server.
It is assumed that you are installing version 4.5 of vFabric Hyperic;this version includes the tc
Server HQ plug-in in all standard distributions.
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 fromscratch;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.Open a terminal (Unix) or Command Prompt (Windows) and create two new directories:one
that will contain the tc Runtime component (such as/home/tcserver) and one that will
contain the HQ Agent and the HQ Server (such as/home/hyperic.) For example,on
Unix:
prompt$ mkdir/home/tcserver
prompt$ mkdir/home/hyperic
3.Fromthe
VMware
Download
Center,download the most recent
vfabric-tc-server-standard-2.5.X-X.zip file and unzip the contents into the
tc Runtime directory you created in the preceding step.The X-X in the zip file name is the
release number and type,for example 0-RELEASE.
This action is all that is required to install tc Runtime;there is no installer program.
For example,if you created a directory called/home/tcserver in the preceding step,and
downloaded the Standard Edition file in the/home/Downloads directory:
prompt$ cd/home/tcserver
prompt$ unzip/home/Downloads/vfabric-tc-server-standard-2.5.0-RELEASE.zip
After you unzip the ZIP file you will have a directory called
/home/tcserver/vfabric-tc-server-standard-2.5.X-X.This directory
Quick Start Instructions 3
vFabric tc Server 2.5 3
contains all the tc Runtime files and directories.
4.Fromthe
VMware
Download
Center,download the VMware vFabric Hyperic Server and
Agent distribution and unpack it into a temporary directory.
Be sure you download version 4.5.1.x of HQ which includes the tc Server HQ plug-in.
Download both the HQ Server and Agent components.You can download a distribution for
your particular platform,such as Windows or Linux,or you can download a platform-neutral
distribution that does not contain a JDK or database (labelled noJRE.) If you download the
latter distribution,you must also install a database server,such as Oracle or Postgres,because
the platform-neutral version of HQ does not include one.The platform-specific versions
include an evaluation database server to get you started.
See the
vFabric
Hyperic
Documentation for details.
5.Fromyour terminal window or Command Prompt,change to the temporary directory in
which you unpacked the HQ distribution and execute the setup.sh (Unix) or setup.bat
(Windows) script.
For example,if you downloaded and unpacked the HQ distribution into the
/home/Downloads directory,you will have a sub-directory called
hyperic-hq-installer:
prompt$ cd/home/Downloads/hyperic-hq-installer
prompt$./setup.sh
After accepting the terms of agreement,enter 1,2 to install both the HQ Server and HQ
Agent.The script asks a few more questions,such as an encryption key for encrypting the
database-user password and the directory in which you will install HQ Server and Agent
(/home/hyperic in our example.) If you are installing a platform-specific version of HQ,
the setup.sh script might ask you to run another script as the root user.If you are
installing the platform-neutral version of HQ,the script asks for information about your
database,including the database URL,name and password of the user that connects to the
database.For more information,see the
vFabric
Hyperic
Documentation.
When the setup.sh script completes,HQ Server is installed in
/home/hyperic/server-4.5.X.X-EE and the HQ Agent is installed in the directory
/home/hyperic/agent-4.5.X.X-EE.
To create a tc Runtime instance and start all components:
1.Fromyour terminal window or Command Prompt,change to the tc Runtime directory and
execute the tcruntime-instance command to create a basic tc Runtime instance
(called myserver in the example):
prompt$ cd/home/tcserver/vfabric-tc-server-standard-2.5.X.X
prompt$./tcruntime-instance.sh create myserver
4 Getting Started
4 Quick Start Instructions
2.(Windows only) Use the tcruntime-ctl command to make the new runtime instance a
Windows service:
prompt$ tcruntime-ctl.bat myserver install
3.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
4.Start the HQ Server:
(Windows) First install HQ Server as a Windows service,and then start the server:
prompt> cd\home\hyperic\server-4.5.X.X-EE
prompt> bin\hq-server.bat install
prompt> bin\hq-server.bat start
(Unix) Change to the HQ Server directory and start the server with the hq-server.sh
command:
prompt$ cd/home/hyperic/server-4.5.X.X-EE
prompt$ bin/hq-server.sh start
5.Start the HQ Agent:
(Windows) Install the HQ Agent as a Windows service and then start it:
prompt> cd\home\hyperic\agent-4.5.X.X-EE
bin\hq-agent.bat install
bin\hq-agent.bat start
(Unix) Change to the HQ Agent directory and start the agent with the hq-agent.sh
command:
prompt$ cd/home/hyperic/agent-4.5.X.X-EE
prompt$ bin/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.Assuming 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;this is because this Quick Start section installs both the HQ
Server and Agent on the same computer (host).The default HQ login/password is
hqadmin/hqadmin.
6.Invoke the HQ server console using the URL http://host:7080 in your browser,where
Quick Start Instructions 5
vFabric tc Server 2.5 5
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;it is
called tc Runtime servername.Other resources might also show up,such as the HQ
Agent itself and a database server.Click the Add to Inventory button so you can begin to
manage and monitor the tc Runtime instance.
Click the Help link on the HQ server console for online help.
6 Getting Started
6 Quick Start Instructions
3.Overview of tc Server
3.1 Features of tc Server
vFabric 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:

tc
Server
Enhancements
to
Apache
Tomcat

Easy
Configuration
and
Monitoring
With
vFabric
Hyperic

Enhanced
Diagnostics

tc
Server
Command-line
Interface
and
Command
Scripts
For a detailed comparison between 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.
Easy Configuration and Monitoring with Hyperic
Hyperic is a comprehensive enterprise application management tool for managing and
monitoring tc Runtime instances,Spring-powered applications,and a variety of
Overview of tc Server 7
vFabric tc Server 2.5 7
non-SpringSource platforms and application servers such as Apache Tomcat.The server
instances and applications can be running on multiple computers.Hyperic provides a single
console with powerful dashboards through which you can easily check the health of your
applications.With Hyperic,you can:
• Manage the lifecycle of tc Runtime instances by starting,stopping,and restarting a local or
remote instance.
• 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,JVMoptions such as heap size and enabling
debugging,default server values for JSPs and static content,JDBC datasources,various tc
Runtime connectors,and so on.
• Using the tcsadmin command-line tool,configure a group of tc Runtime instances.
• Deploy a Web application froman 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 tasks,you performthe standard 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
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
8 Getting Started
8 Overview of tc Server
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 Hyperic alerts,see
tc
Server
Administration
Guide,under Managing tc Runtime-Related Hyperic 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 tc Server (tc Runtime) is an enterprise version of Apache Tomcat.tc
Runtime is a drop-in replacement for Apache Tomcat,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.
tc Runtime also adds many business-critical features to standard Apache Tomcat.The following
Overview of tc Server 9
vFabric tc Server 2.5 9
sections compare the two:

Standard
Application
Server
Features

Enterprise
Application
Server
Features

Business-Critical
Operational
Features
Standard Application Server Features
tc Runtime and Apache Tomcat share key standard features of application servers.
Table 3.1.Standard Application Server Feature Comparison
Application Server Features
vFabric tc Runtime
Apache Tomcat
Servlet 2.5 and 3.0 support
Yes
Yes
Java Server Pages (JSP) 2.1 and 2.2
support
Yes
Yes
HTTP session clustering
Yes
Yes
Advanced I/O features
Yes
Yes
Pre-built advanced non-blocking I/O
components
Yes
Yes
Basic Windows service wrapper
Yes Yes
Enterprise Application Server Features
Because tc Runtime is based on Apache Tomcat,it provides a powerful yet lightweight platform
that is compatible with existing Tomcat-based applications and with Web applications that run
on other Java EE application servers such as IBMWebSphere Application Server or Oracle
WebLogic Server.Applications can be seamlessly moved fromApache Tomcat to tc Runtime to
gain the benefits that tc Runtime provides beyond the base Apache Tomcat.
Table 3.2.Enterprise Application Server Feature Comparison
Enterprise Application Server
Features
vFabric tc Runtime
Apache Tomcat
Multiple runtime instances froma
single binary installation
Yes
No
10 Getting Started
10 Overview of tc Server
Enterprise Application Server
Features
vFabric tc Runtime
Apache Tomcat
New high-concurrency JDBC
connection pool`
Yes
No
Preconfigured for JMX management
Yes
No
Includes latest security vulnerability
and bug fixes
Yes
Rebuild Tomcat yourself
to apply incremental
fixes.
Includes a control script compatible
with Unix etc/init.d
Yes
No
Enhanced Windows service wrapper
Yes No
tc Server offers scripts and templates to simplify performing a number of advanced
configurations.
Table 3.3.Advanced Configuration Tools Comparison
Advanced Configuration
Features
vFabric tc Server
Apache Tomcat
Templated production-ready
configuration out-of-the-box
Yes
No
Create Tomcat single server
configuration
Yes
No
Modify general server
configuration including JVM
startup parameters
Yes
No
Modify context container
configuration
Yes
No
Modify server defaults for
JSPs and static content
Yes
No
Add,modify,and delete
JDBC datasources
Yes
No
Modify HTTP and AJP
connector settings
Yes
No
Create and view general
services
Yes
No
Overview of tc Server 11
vFabric tc Server 2.5 11
Advanced Configuration
Features
vFabric tc Server
Apache Tomcat
Modify general engine
configuration
Yes
No
Pre-tuned JVMoptions
Yes No
Business-Critical Operational Features
tc Runtime includes advanced,distributed management and monitoring capabilities through a
centralized management console called Hyperic user interface.
The tables in this section list the capabilities that tc Runtime provides over and above the base
Apache Tomcat and also notes the features that Hyperic provides for existing Apache Tomcat
environments.
tc Runtime provides a wide range of capabilities that enable developers,administrators,and
operators to centrally diagnose,measure,and monitor the distributed application infrastructure.
Table 3.4.Diagnostics,Metrics,and Monitoring Feature Comparison
Diagnostics,Metrics,and Monitoring
Features
vFabric tc Runtime
Apache Tomcat
Application deadlock detection
Yes
No
Uncaught exception detection
Yes
No
Garbage collection metrics,including
throughput and count
Yes
No
SQL query time monitoring metrics
Yes
No
Enhance response time monitoring
metrics
Yes
No
Enhanced connection pool health
metrics
Yes
No
Enhanced thread pool health metrics
Yes
No
Role-based customizable dashboard
Yes
Yes (via Hyperic)
Automated inventory of application
servers and software resources
Yes
Yes (via Hyperic)
Real-time metric collection and
monitoring of tc Runtime,Tomcat,
Yes
Yes (via Hyperic)
12 Getting Started
12 Overview of tc Server
Diagnostics,Metrics,and Monitoring
Features
vFabric tc Runtime
Apache Tomcat
Apache Web server,Apache
ActiveMQ,underlying JVM,operating
system,and other resources
Charting and graphing performance
Yes
Yes (via Hyperic)
Advanced alerting:multi-conditional,
availability,event,and recovery alerts,
group-based alerting,and escalation
schemes
Yes
Yes (via Hyperic)
Log file tracing,alerts on event levels
Yes
Yes (via Hyperic)
Alerts based on configuration file
updates
Yes
Yes (via Hyperic)
Performance baselining for alert
thresholds
Yes Yes (via Hyperic)
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 Features
vFabric tc Runtime
Apache Tomcat
Secure,distributed,JMX-based server
management
Yes
No
Create application server groups
Yes
Yes (via Hyperic)
Application server start/stop/restart
fromcentral console
Yes
Yes (via Hyperic)
List deployed applications and current
status
Yes
No
Application
deploy/undeploy/reload/start/stop
Yes
No
Security and access/authorization
control
Yes
Yes (via Hyperic)
Scheduled control:maintenance
activities,on-demand actions,
scheduled remediation actions,or
Yes Yes (via Hyperic)
Overview of tc Server 13
vFabric tc Server 2.5 13
Centralized Operations and
Management Features
vFabric tc Runtime
Apache Tomcat
scheduled responses to alert conditions
tc Server 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 Features
vFabric tc Runtime
Apache Tomcat
List deployed servers
Yes
No
Create server groups
Yes
No
Add and delete servers to and
fromgroups
Yes
No
List deployed applications,
including current status
Yes
No
Deploy application WAR file
Yes
No
Undeploy application
Yes
No
Start,stop,and reload
deployed applications
Yes
No
Get (download) configuration
files and JVMparameters
froma server
Yes
No
Modify configuration files on
an individual server
Yes
No
Set (push) configuration files
and JVMparameters to a
server group
Yes
No
Start,stop,and restart a server
or group of servers
Yes No
3.3 tc Server Editions
tc Server is available in the following editions:
14 Getting Started
14 Overview of tc Server

Developer
Edition

Standard
Edition

Spring
Edition
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 Developer,an application that provides real-time
visibility into the behavior and performance of user applications.The tc Server Developer
Edition contains a template called insight that includes the Spring Insight application.You
use this template to create new tc Runtime instances enabled with Spring Insight.See
Using
Spring
Insight
Developer for help setting up and using Spring Insight.(tc Server Developer
Edition does not include access to Hyperic Server and Agent.)
The Developer Edition is distributed as either a ZIP or compressed TAR file with the following
names:
• vfabric-tc-server-developer-2.5.X.RELEASE.zip
• vfabric-tc-server-developer-2.5.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 Developer.
With the Standard Edition,you have access to the vFabric Hyperic management system,which
(as of version 4.5) includes the tc Server HQ plugin in the general distribution.Install vFabric
Hyperic if you want to use Hyperic to configure and manage the tc Runtime.If you do not want
to use Hyperic to manage tc Runtime instances and want to use the tc Runtime on its own,install
only the tc Runtime.
The Standard Edition is distributed as either a ZIP or compressed TAR file with the following
names:
• vfabric-tc-server-standard-2.5.X.RELEASE.zip
Overview of tc Server 15
vFabric tc Server 2.5 15
• vfabric-tc-server-standard-2.5.X.RELEASE.tar.gz
To download an evaluation of Hyperic,go to the
VMware
Downloads
Center.
Spring Edition
The Spring Edition of tc Server includes the Standard Edition and Hyperic management
components,plus production optimizations for Spring-based applications in the formof
instrumented JARs for the following Spring technologies:Spring Framework,Spring Security,
Spring Web Flow,and Spring Web Services.
3.4 How tc Server and Hyperic Work Together
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 Hyperic management capabilities.This section shows how the
runtime component of tc Server (called tc Runtime) and the Hyperic components (Hyperic
Server and Hyperic 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,Hyperic Agent,and
Hyperic 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 Hyperic Server and
Hyperic Agent,which are used to manage the tc Runtime instances.
16 Getting Started
16 Overview of tc Server
Figure 3.1.Installing on One Computer
In the preceding figure,the Hyperic Server is managing just one tc Runtime instance.The
Hyperic 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
Hyperic Agent.
Figure 3.2.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 Hyperic Server on computerB.In this case,you must
install the Hyperic Agent on computerA so that the Hyperic Server is able to manage the tc
Runtime instances on computerA fromcomputerB.computerA is referred to as a
managed node.
Overview of tc Server 17
vFabric tc Server 2.5 17
Figure 3.3.Installing on Two Computers
In another scenario,you host the Hyperic 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 Hyperic Agent on each computer (managed node) that hosts the tc Runtime
instances.
In the following figure,for example,computerC might be a Windows platformwhile all the
rest of the computers are Unix.Also note that each computer has a different set of tc Runtimes
installed,but only one Hyperic Agent.In the figure,all computers except computerB are
managed nodes.
18 Getting Started
18 Overview of tc Server
Figure 3.4.Installing on Multiple Computers
3.5 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.

Apache
Tomcat
6.0
Documentation

Apache
Tomcat
7.0
Documentation

Apache
Tomcat
FAQ
The Hyperic management component of tc Server provides monitoring and management for your
Web infrastructure.You can use it to streamline operations,manage infrastructure complexity,
Overview of tc Server 19
vFabric tc Server 2.5 19
and drive service level improvements.The Hyperic user interface includes online help for both
generic Hyperic functionality,as well as tc Server related functionality.For detailed
documentation about Hyperic:

vFabric
Hyperic
Documentation
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:

Spring
Framework
Reference
Manuals
and
Javadoc

Java
Servlet
Technology

JavaServer
Pages
(JSP)
Technology
20 Getting Started
20 Overview of tc Server
4.Release Notes
The following sections contain release-specific information about vFabric tc Server.

Versioning
Process

What's
New
and
Changed
in
This
Release?

Supported
and
Tested
Configurations

Fixed
Issues

Restrictions
4.1 Versioning Process
The tc Server bundle has a version number separate fromthe underlying components.Minor
revisions,maintenance updates,and service releases of any set of underlying components
increment the fully qualified bundle version.As of the 2.5 release,the bundle contains the
following separately versioned components.The initial major version of each component is
noted.Specific downloads have fully qualified version information on each component.
• tc Runtime:Apache Tomcat-based runtime container,major versions 6.0 and 7.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,tomcat-6.0.32.A-RELEASE.
• tc Server Hyperic Plug-In:vFabric Hyperic plug-in that enables advanced management and
monitoring,major version 2.5.
• Hyperic Agent:Agent portion of bundle,major version 4.5.
• Hyperic Server:Hyperic Server,preconfigured with the tc Server Hyperic plug-in,major
version 4.5.
4.2 What's New and Changed in This Release?
2.5.1 Maintenance Release
tc Runtime 7.0 Version Update
Release Notes 21
vFabric tc Server 2.5 21
The tc Runtime 7.0 version has been updated to use tomcat-7.0.16.A-RELEASE as its
core.
New Option for Hyperic tc Server Command-Line create-group Command
The Hyperic tc Server command-line interface create-group command has a new
--version option to specify the tc Runtime version.The option accepts values of 6.0 and
7.0.Only servers of the specified tc Runtime version can be added to a group.
2.5.0 Release
The 2.5.0 release of tc Server includes support for tc Runtimes based on Tomcat 6.0 and Tomcat
7.0.You can choose the version of tc Runtime when you create an instance.tc Runtime 7.0
offers several new features,including support for the Servlet 3.0,JSP 2.2,and JSP-EL2.2
specifications,as well as security improvements.
Following are additional features and changes that are new to this tc Server release:
• When using tc Runtime 7.0,you can deploy multiple versions of a web application with the
same context path simultaneously by appending a version number to the context name.This
makes it possible to deploy an updated application without interrupting existing sessions.New
requests for the application are routed to the newest version of the application.Requests that
have existing session information continue to use the version of the application that is
managing the session.See
Deploying
Multiple
Versions
of
an
Application in this guide.See
The
Context
Container at the Apache website for more details about this feature.
• The tcruntime-instance command has a new upgrade verb that you can use to
upgrade a tc Server instance created with tc Server 2.0 or tc Server 2.1 to tc Server 2.5.You
can specify the new tc Runtime version to use or allow the upgraded instance to continue
using the same tc Runtime version,if that version is available in the new tc Server release.
4.3 Supported and Tested Configurations
The sections that follow list the configurations supported by version 2.5.X of the tc Runtime
component.
For supported configuration information about the Hyperic Server and Agent,see
Installation
Requirements.
Supported Java EE Specifications
22 Getting Started
22 Release Notes
SpringSource tc Runtime supports:

Java
Servlets
2.5 (tc Runtime 6) and
Java
Servlets
3.0 (tc Runtime 7)

JavaServer
Pages
(JSP)
2.1 (tc Runtime 6) and
JavaServer
Pages
(JSP)
2.2 (tc Runtime 7)
Supported JRE Versions
SpringSource tc Runtime runs on version 1.6 of the Java Runtime Environment (JRE).
Supported Configurations:tc Runtime
The following table lists the supported configurations for running the tc Runtime.Other
configurations may be supported on request;contact your sales representative for details.
Because you typically install and run the Hyperic Agent on the same computer as the tc Runtime,
you should also consult
HQ
Agent
Requirements.
SpringSource recommends that you follow the guidance of your operating systemor JVM
vendor when deciding which patch levels should be applied to your computer.In general,the
latest patch update levels are recommended.
Table 4.1.Supported Configurations
Operating
System
Major Version
Chip
Architecture
JVM
tc Runtime
Version
RedHat
Enterprise Linux
(RHEL)
V5
x86 32/64 bit
Sun HotSpot 1.6
2.5.X
Ubuntu
10.04 LTS
x86 64 bit
Sun HotSpot 1.6
2.5.X
Windows
2008 Server
(SP2)
x86 32/64 bit
Sun HotSpot 1.6
2.5.X
Windows
2003 Server (SP2
and newer)
x86 32 bit
Sun HotSpot 1.6 2.5.X
Tested Configurations:tc Runtime
The following tables list specifically tested patch update levels for the latest 2.5.X version of tc
Runtime.This table is updated as new configurations are tested.
Release Notes 23
vFabric tc Server 2.5 23
Table 4.2.Tested Configurations
Operating
System
Major Version
Chip
Architecture
(Tested)
Fully Qualified
JVMVersion
(Tested)
Version of tc
Runtime
(Tested)
RedHat
Enterprise Linux
(RHEL)
V5 (Kernel
2.6.18-164.28.1.el5PAE)
x86 32 bit
Sun HotSpot
1.6.0_20
2.5.0
RedHat
Enterprise Linux
(RHEL)
V5 (Kernel
2.6.18-164.28.1.el5)
x86 64 bit
Sun HotSpot
1.6.0_20
2.5.0
Ubuntu
10.04 LTS
x86 64 bit
Sun HotSpot
1.6.0_22
2.5.0
Windows
2008 Server
(SP2)
x86 32 bit
Sun HotSpot
1.6.0_18
2.5.0
Windows
2008 Server
(SP2)
x86 64 bit
Sun HotSpot
1.6.0_18
2.5.0
Windows
2003 Server
(SP2)
x86 32 bit
Sun HotSpot
1.6.0_18
2.5.0
4.4 Fixed Issues
The following table lists the product issues that were fixed in the 2.5.1 maintenance release.
Table 4.3.Fixed Issues in 2.5.1
Issue ID
Description
TCS-2086
Graceful shutdown using the tcruntime-ctl stop command does not
work for tc Runtime 7 instances started with the tcruntime-ctl run
command.
TCS-2102
Clarify documentation about upgrading an unpinned tc Server 2.0.x or 2.1.x
instance to tc Server 2.5.0 with the tcruntime-instance.sh
upgrade command.
TCS-2258
The template file
templates/base-tomcat-7/conf/catalina-fragment.properties
is missing a line continuation character (,\) before the end of a line in the
definition of the
24 Getting Started
24 Release Notes
Issue ID
Description
tomcat.util.scan.DefaultJarScanner.jarsToSkip
property.
TCS-2276
Clarify documentation about the differences between the
tcruntime-instance modify-version and
tcruntime-instance upgrade commands.
TCS-2277
The Hyperic tc Server command-line interface always assumes tc Runtime
groups are based on Tomcat 6.This is fixed in the 2.5.1 release with the
addition of the --version option for the create-group command.
TCS-2279 Update documentation to show the addition of the application version to the
output of the Hyperic tc Server CLI list-applications command.
4.5 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.
Release Notes 25
vFabric tc Server 2.5 25
26 Getting Started
26 Release Notes
5.What Are the Main Steps Required to Get
Going?
This chapter provides a roadmap to the high-level steps you performto get vFabric 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 vFabric Hyperic user interface to configure and
manage a tc Runtime instance or group.
1.
Before
You
Begin
2.
Installing
tc
Server
and
Creating
a
New
tc
Runtime
Instance
3.
Starting
the
Components
and
Doing
Initial
Configuration
4.
Exploring
the
Features
of
tc
Server
5.1 Before You Begin
You install tc Server by installing its components:the tc Runtime and the management
components (Hyperic 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 Standard Edition,which includes
access to Hyperic HQ to manage and monitor tc Server,you install the tc Runtime,the HQ
Server,and the HQ Agent.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
This section assumes 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.
It is also assumed in most of this documentation that you will use the separate layout
for tc Runtime instances,rather than the combined layout (which is similar to the
standard Apache Tomcat layout.) In the separate layout,CATALINA_HOME and
CATALINA_BASE point to separate directories;in the combined layout they point to
the same directory.The default when you create an instance is to use the separate
What Are the Main Steps 27
vFabric tc Server 2.5 27
layout because it offers many benefits over the combined layout,although you can of
course use the latter if you wish by specifying the --layout option of the
tcruntime-instance script.See
Differences
Between
the
Separate
and
Combined
Layouts for more information.Unless otherwise specified,the rest of the
documentation assumes the separate layout.
5.2 Installing tc Server and Creating a New tc Runtime
Instance
This high-level installation step includes the following sub-steps:
1.Install the tc Runtime on one or more computers.You performthis step for all editions of tc
Server:Developer,Standard,and Spring.
See
Installing
tc
Server:
Main
Steps.
2.If you want to install the HQ management components,you install the HQ Server once.
See
Installing
Standard
Edition
(Including
HQ
Management
Components).
3.If you want to install the HQ management components,install the HQ Agent on all
computers on which you installed the tc Runtime.
See
Installing
Standard
Edition
(Including
HQ
Management
Components).
4.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 performthe 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.
28 Getting Started
28 What Are the Main Steps
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 performon 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.
What Are the Main Steps 29
vFabric tc Server 2.5 29
30 Getting Started
30 What Are the Main Steps
6.Installing tc Server
This chapter describes how to install the various editions of vFabric tc Server.

Before
You
Begin:
System
Requirements

Installing
tc
Server:
Main
Steps

Overview
of
tc
Server
Directories,
Variables,
and
Configuration
6.1 Before You Begin:SystemRequirements
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 the tc Runtime component of tc
Server.If you are installing the HQ components,the JDK or JRE requirement depends on
whether you install the platform-specific or platform-neutral version;only the latter requires a
JDK or JRE because the former bundles one.See
Supported
Configurations for platform-specific
details of the JDK or JRE versions that are supported and have been tested.
For most platforms you can download and install the Sun JDK or JRE,although for IBM
computers you might want to install the IBM-specific JDK or JRE.The following links point to
download Web sites:

Sun
JDK
and
JRE
Downloads

IBM
JDK
and
JRE
Downloads
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 systemenvironment variable to point to the
Installing tc Server 31
vFabric tc Server 2.5 31
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 also install the HQ Server and Agents management components using the
platform-neutral version of the HQ distribution.
The HQ Server uses a database to store its metadata.The platform-neutral version of HQ Server
does not,however,bundle a database.This means that if you do not have a database server
already installed on either the computer on which you are going to install HQ Server or on an
accessible remote computer,then you must download and install one.The platform-specific
versions of the HQ distribution bundle a non-production database for you to get started,although
it is not recommended that you use this database for production purposes.
Use Oracle 10g/11g,PostgreSQL,or MySQL 5.x with HQ Server.During the installation of HQ
Server,you will provide the database URL for JDBC connection and the database username and
password.
To set up one of these databases for use with HQ Server,see
Set
Up
Hyperic
Database.
Installing on Unix Platforms:Important Notes
This section contains notes about installing tc Server on Unix systems.
tar Command Compatibility
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 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) froman external source.For example,the Web site
Sunfreeware.comincludes 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.
32 Getting Started
32 Installing tc Server
If you have installed GNUtar,then substitute the command gtar for any references to tar in
the following install procedure.
Spaces in File and Directory Names
On Unix systems,avoid pathnames containing spaces.Directory and file names containing
spaces can cause errors in scripts when added to search paths or specified as command
arguments.
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.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.

Installing
Developer
Edition

Installing
Standard
Edition
(tc
Runtime
Only)

Installing
Standard
Edition
(Including
HQ
Management
Components)

Installing
Spring
Edition
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 pre-4.5 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 fromthe
VMware
Download
Center.
Installing tc Server 33
vFabric tc Server 2.5 33
The Developer Edition is distributed as either a ZIP or compressed TAR file with the
following names:
• vfabric-tc-server-developer-2.5.X.RELEASE.zip
• vfabric-tc-server-developer-2.5.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 vfabric-tc-server-developer in the main tc Server
installation directory that contains the tc Runtime utility scripts,the templates directory,the
tomcat-version directories,and so on.
The templates directory in turn contains a template called insight that contains the
Spring Insight feature.
See
Overview
of
tc
Server
Directories,
Variables,
and
Configuration
Files for details.
5.Create a tc Runtime instance that contains Spring Insight by specifying the insight
template.The exact steps depend on your platform(Unix or Windows).
Unix:Change to the/home/tcserver/vfabric-tc-server-developer
directory and execute the tcruntime-instance.sh script to create an instance.For
example:
prompt$ cd/home/tcserver/vfabric-tc-server-developer
prompt$./tcruntime-instance.sh create insight-instance -t insight
Windows:Change to the c:\home\tcserver\vfabric-tc-server-developer
directory and execute the tcruntime-instance.bat script to create an instance:
prompt> cd c:\home\tcserver\vfabric-tc-server-developer
prompt> tcruntime-instance.bat create insight-instance -t insight
6.Start the new tc Runtime instance.The exact steps depend on your platform(Unix or
Windows).
Unix:Execute the tcruntime-ctl.sh script to start the instance.For example:
prompt$./tcruntime-ctl.sh insight-instance start
Windows:Execute the tcruntime-ctl.bat script to first install the tc Runtime instance
as a Windows service and then start it:
34 Getting Started
34 Installing tc Server
prompt> tcruntime-ctl.bat insight-instance install
prompt> tcruntime-ctl.bat insight-instance start
Subsequently,you can use tcruntime-ctl.bat or the Windows Services console to
start and stop the tc Runtime instance.In the Windows Services console,the tc Runtime
instance is displayed with the name SpringSource tc Runtime - unique-name,
where unique-name is a combination of server name and server directory.
7.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 discussed in this section,such as creating tc Runtime
instances and starting them,see
Next
Steps.
Installing Standard Edition (tc Runtime Only)
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
VMware
Download
Center page under VMware vFabric tc Server,download the
vFabric tc Server Standard Edition package distribution.
Choose the ZIP or the compressed TAR file distribution:
• vfabric-tc-server-standard-2.5.X.RELEASE.zip
• vfabric-tc-server-standard-2.5.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 action is all that is required to install tc Runtime;there is no installer program.
Installing tc Server 35
vFabric tc Server 2.5 35
For example,if you created a directory called/home/tcserver in the preceding step,and
downloaded the Standard Edition file in the/home/Downloads directory:
prompt$ cd/home/tcserver
prompt$ unzip/home/Downloads/vfabric-tc-server-standard-2.5.0.RELEASE.zip
This creates a directory called vfabric-tc-server-standard-2.5.0.RELEASE 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 (Including HQ Management
Components)
This section describes how to install one or more instances of tc Runtime and HQ Agent together
(also referred to as a managed node),as well as a single HQ Server;assuming the HQ
components are version 4.5 or later,both HQ components automatically include the tc Server
HQ plug-in.
Read
How
tc
Server
and
HQ
Work
Together to understand the various installation scenarios for
managed nodes and the HQ Server.Then decide which tc Server components (tc Runtime,HQ
Agent,and HQ Server) you are going to install on your computer(s).The typical scenarios are:
• 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
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.
36 Getting Started
36 Installing tc Server
1.On the computer on which you are going to install the managed node (tc Runtime and
HQAgent),download and install a JDK or JRE,if you have not already done so.See
Before
You
Begin:
System
Requirements.
2.Open a terminal (Unix) or Command Prompt (Windows) and create two new directories:one
that will contain the tc Runtime component (such as/home/tcserver) and one that will
contain the HQ Agent (such as/home/hyperic.) If you wish,you can install tc Runtime
and HQ Agent in the same directory,but it is assumed in this procedure that you will install
themin different directories.For example,on Unix:
prompt$ mkdir/home/tcserver
prompt$ mkdir/home/hyperic
3.Fromthe
VMware
Download
Center,download the vFabric tc Server Standard Edition
distribution.Choose the ZIP or compressed TAR file distribution:
• vfabric-tc-server-standard-2.5.X.RELEASE.zip
• vfabric-tc-server-standard-2.5.X.RELEASE.tar.gz
4.Unzip or untar the tc Server distribution file into the/home/tcserver directory.
This action is all that is required to install tc Runtime;there is no installer program.
For example,if you created a directory called/home/tcserver in the preceding step,and
downloaded the Standard Edition file in the/home/Downloads directory:
prompt$ cd/home/tcserver
prompt$ unzip/home/Downloads/vfabric-tc-server-standard-2.1.0-RELEASE.zip
A directory called vfabric-tc-server-standard 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.
5.Fromthe
VMware
Download
Center,download the Agent-only 4.5 Hyperic HQ EE
distribution and unpack it into the/home/hyperic directory.
The HQ Agent will be installed in the directory/home/hyperic/agent-4.5.X.X-EE.
6.On the computer on which you are going to install HQServer,determine whether you
need to download and install a JDK/JRE or database server.You typically only need to do
this if you are installing the platform-neutral version of HQ Server;the platform-specific
version bundles a JDK/JRE and non-production database server to get you started.See
Before
you
Begin:
System
Requirements.
If you are using your own database server,obtain the URL and username/password used to
Installing tc Server 37
vFabric tc Server 2.5 37
connect to it,because the installation programfor HQ Server will ask for it.
7.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 HQ Agent or tc Runtime directory that you already created (/home/tcserver in our
example).
8.Fromthe
VMware
Download
Center,download the Hyperic HQ EE (Enterprise Edition)
distribution and unpack it into a temporary directory.
Be sure you download version 4.5 of HQ which automatically includes the tc Server HQ
plug-in.You can download a distribution for your particular platform,such as Windows or
Linux,or you can download a platform-neutral distribution that does not contain a JDK or
database (labelled noJRE.)
9.Fromyour terminal window or Command Prompt,change to the temporary directory in
which you unpacked the HQ distribution and execute the setup.sh (Unix) or setup.bat
(Windows) script.
For example,if you downloaded and unpacked the HQ distribution into the
/home/Downloads directory,you will have a sub-directory called
hyperic-hq-installer:
prompt$ cd/home/Downloads/hyperic-hq-installer
prompt$./setup.sh
After accepting the terms of agreement,enter 1 to install just the HQ Server (you installed
the HQ Agent in a preceding step.) The script asks a few more questions,such as an
encryption key for encrypting the database-user password and the directory in which you will
install HQ Server (/home/hyperic in our example.) If you are installing a
platform-specific version of HQ,the setup.sh script might ask you to run another script as
the root user.If you are installing the platform-neutral version of HQ,the script asks for
information about your database,including the database URL,name and password of the
user that connects to the database.For more information,see the
vFabric
Hyperic
Documentation.
When the setup.sh script completes,HQ Server is installed in
/home/hyperic/server-4.5.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.
38 Getting Started
38 Installing tc Server
See
Next
Steps for links to post-installation procedures.
Installing Spring Edition
1.On the
VMware
Download
Center page under VMware vFabric tc Server,download the tc
Server Standard Edition and the Instrumented Spring JARs.
2.Follow the instructions in
Installing
Standard
Edition
(Including
HQ
Management
Compnents) 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
vfabric-tc-server-edition subdirectory,where edition refers to the edition of tc
Server you are using (standard or developer.) 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.tc Server
Installing tc Server 39
vFabric tc Server 2.5 39
2.5 includes runtimes based on both Tomcat 6.0 and Tomcat 7.0.This is the basic
CATALINA_HOME directory;Apache Tomcat users will recognize its contents.
• templates.Out-of-the-box templates for creating customized tc Runtime instances,such as
cluster-node enabled or SSL-ready.You optionally specify one or more of these templates
when you run the tcruntime-instance.sh|bat script to create a new tc Runtime
instance.
• lib.JAR files that implement the templating mechanismand are used by the
tcruntime-instance script..
• tcruntime-instance.sh|bat.Scripts for creating new tc Runtime instances.
When you create a new tc Runtime instance with this script,the script creates (by default) a
subdirectory of the vfabric-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.
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/vfabric-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
(developer or standard),and version is the version of the underlying Tomcat,such
as 6.0.30.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,then the CATALINA_BASE of the instance is
INSTALL_DIR/vfabric-tc-server-standard/myserver by default.
40 Getting Started
40 Installing tc Server
The following variables are"exposed"by tc Runtime,which means that you can set themor use
themin 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 the tc Runtime instance write its stdout and stderr messages to
/home/tcserver/tcruntime-instance-6.log,set the variable in your
environment or setenv.sh as follows:
CATALINA_OUT=/home/tcserver/tcruntime-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.
Installing tc Server 41
vFabric tc Server 2.5 41
• 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 JVMfor 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
42 Getting Started
42 Installing tc Server
passwords.
• logging.properties.Configures the logging systemof the tc Runtime instance.
Installing tc Server 43
vFabric tc Server 2.5 43
44 Getting Started
44 Installing tc Server
7.Post-Installation Tasks
After you install the components of vFabric 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.)
7.1 Creating a New tc Runtime Instance
The following sections describe how to create new instances of tc Runtime and provide related
information:

Creating
tc
Runtime
Instances:
Typical
Steps

tcruntime-instance.sh
Reference

Pinning
tc
Runtime
Instances
to
a
Specific
Version

Best
Practice:
Naming
tc
Runtime
Instances

Creating
a
tc
Runtime
Instance
with
a
Template

Templates
Provided
by
tc
Runtime

Differences
Between
the
Separate
and
Combined
Layouts
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/vfabric-tc-server-edition-release directory,
where INSTALL_DIR refers to the main tc Server installation directory,such as
/home/tcserver,edition refers to the edition of tc Server you are using
Post-Installation Tasks 45
vFabric tc Server 2.5 45
developer or standard.),and release is the release specifier For example:
prompt$ cd/home/tcserver/vfabric-tc-server-standard-2.5.0-RELEASE
3.Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat
(Windows) script,passing it the create serverName option.Replace serverName
with the name of your new tc Runtime instance.See
Best
Practice:
Naming
tc
Runtime
Instances for tips on naming an instance.
For example,on Unix:
prompt$./tcruntime-instance.sh create myserver
On Windows:
prompt> tcruntime-instance.bat create myserver
When the preceding sample command completes,the new tc Runtime instance is located by
default in the INSTALL_DIR/vfabric-tc-server-edition/myserver directory
(such as/home/tcserver/vfabric-tc-server-standard/myserver);you can
specify a different instance directory with the --instance-directory directory
option.This directory is also the value of the CATALINA_BASE variable for this tc Runtime
instance.For example:
prompt> tcruntime-instance.bat create myserver --instance-directory/home/tcserver/instances
In the preceding example,the myserver instance directory will be
/home/tcserver/instances/myserver.
By default,the tc Runtime instance uses the JAVA_HOME environment variable for the Java
binaries,or the instance uses the java binary that it found in the PATH environment variable
when it started.You can specify a specific JAVA_HOME using the --java-home option.
The ports of the tc Runtime instance are the default values:
• HTTP listen port:8080
• JMX port:6969
• AJP port:8009
• Shutdown port:-1
The preceding tcruntime-instance sample did not specify the --version option,so the
instance is pinned to the highest tc Runtime version located in the installation directory,for
example 7.0.8.A-RELEASE.You can use the modify-version verb to unpin the
instance.See
Pinning
tc
Runtime
Instances
to
a
Specific
Version for more information.
46 Getting Started
46 Post-Installation Tasks
When you use the tcruntime-instance.sh|bat command script to create an instance,
you can specify additional optional parameters,as described in
tcruntime-instance.sh
Reference.
For example,you can use the --property option to specify a configuration property.
tcruntime-instance.sh Reference
The tcruntime-instance command script has five possible command verbs,used to
create,modify,or upgrade a tc Runtime instance,list the existing instances,or display help for
the command script.Each command has its own set of options,as described in the tables in this
section.Depending on the command,you must specify the name of a tc Runtime instance.The
general syntax for each of the commands follows;click on the link to see the options for that
particular command:
tcruntime-instance
create
instance-name
[options]
tcruntime-instance
modify-version
instance-name
[options]
tcruntime-instance
upgrade
instance-name
[options]
tcruntime-instance
list
[options]
tcruntime-instance
help
[command-name]
The create Command
Use the create command to create a new tc Runtime instance.
The command requires that you specify a name for the new tc Runtime instance directly after the
create text.
When you create a new instance,and you do not specify the --template option to apply one
or more specific templates,the tcruntime-instance script creates a basic tc Runtime
instance that uses the default template (called bio);this template adds the Blocking IO (BIO)
HTTP Connector to the server.xml of the instance.You can use the --template option to
apply one or more templates so that the instance is automatically configured for a particular
feature,such as the NIO connector,clustering,or SSL.
Examples of creating new tc Runtime instances are shown after the options reference table.
The following table lists options for the create command of
tcruntime-instance.sh|bat.When specifying the most common options,you can use
either the short form(such as -i) or the long form(such as --instance-directory);less
common options support only the long form.
Table 7.1.Options of the create Command
Option (Long Form)
Option (Short Form,if
available)
Description
--force
N/A
Forces the script to create a new tc Runtime instance,
even if one already exists.By default the script does
not force the creation.
Post-Installation Tasks 47
vFabric tc Server 2.5 47
Option (Long Form)
Option (Short Form,if
available)
Description
If you specify this parameter and a tc Runtime
instance with the name already exists,the script
replaces only the existing bin and conf directories;
the script does not replace the other directories,such
as lib or temp.It is assumed in this case that you
do not want to touch the user-specific files,such as
Web applications.
To update the tc Runtime version used by an
instance,use the modify-version command,not
the --force option.
--help
-h
Outputs usage information about the create
command usage.
--interactive
N/A
Tells the script to interactively ask for configuration
properties.For example,use this parameter if you
want to change the default port numbers,as listed in
Creating
tc
Runtime
Instances:
Typical
Steps.
Warning:Be sure that all tc Runtime instances on
the same computer have unique port numbers.
--instance-directory
instanceDir
-i instanceDir
Replace instanceDir with the full or relative
pathname of the directory in which you want the new
tc Runtime instance to be created.If you specify a
relative directory pathname,the directory is relative
to the directory fromwhich you are running the
tcruntime-instance.sh|bat script.
The default value of this option is the current
working directory.
--java-home
--java-home path_to_jre
N/A
If specified without a path_to_jre value,
hard-codes the JAVA_HOME variable in various files
of the instance,using the global JAVA_HOME
environment variable value.You can also use this
option to specify a different location of the JDK or
JRE.In this case,replace path_to_jre with the
full pathname of the JRE or JDK.
If you do not specify this option at all,then the
instance uses the JAVA_HOME global environment
variable,and does not hard-code the value anywhere.
--layout layout
N/A
Specifies the type of layout you want your new tc
Runtime instance to use:separate or combined.
The default value is separate.
In the separate layout,CATALINA_HOME and
CATALINA_BASE point to different directories;in
the combined layout they point to the same directory,
which means that the tc Runtime binaries are
bundled within your instance.The combined is the
standard Apache Tomcat layout.
Warning:SpringSource recommends that you
always use the separate layout,which is why it is the
48 Getting Started
48 Post-Installation Tasks
Option (Long Form)
Option (Short Form,if
available)
Description
default value if you do not specify this option.For
addiditonal information,see
Differences
Between
the
Separate
and
Combined
Layouts.
--properties-file file
-f file
Specifies the name of a properties file that contains
configuration properties that you want to apply to the
new tc Runtime instance.
When you create the properties file,it should contain
one property per line,in the form
template-name.property-name=value.
The name of the property depends on the template.
For example,the default template (called bio) has
two configuration properties:http.port and
https.port.Other templates might specify their
own configuration properties.If you want to pass
your own values of these properties to the
tcruntime-instance script at the command
line,rather than the instance taking the default
values,create a file such as the following:
bio.http.port=9090
bio.https.port=9191
Then point to this configuration property file using
this option:
--properties-file my-property-file
--property
template.property=value
-p
template.property=value
Specifies a single configuration that you want to
apply to the new tc Runtime instance.
When you create a tc Runtime instance,the
tcruntime-instance script always applies a
template,even if it is the default one (called bio).
Templates usually have configuration properties.For
example,the bio template has two configuration
properties:http.port and https.port.Other
templates might specify their own configuration
properties.If you want to pass your own values of