Getting Started with tc Server
Version 6.0
SpringSource Document build:
January 7, 2010, 3:07:46 PM (PST)


   
Copyright Notice
Copyright © 2009 SpringSource Inc. All rights reserved.
Trademark Notice
SpringSource is a registered trademark of SpringSource, Inc. and/or its affiliates. Other names may be trademarks of their respective owners.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19. SpringSource, Inc., 411 Borel Ave., Suite 101, San Mateo, CA 94402.
This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. SpringSource, Inc. and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.
This software and documentation may provide access to or information on content, products and services from third parties. SpringSource, Inc. and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. SpringSource, Inc. and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.


Version 6.0   Getting Started with tc Server
   
Contents
Introduction to tc Server    
Differences Between tc Server and Apache Tomcat    
Supported Configurations    
Restrictions and Licensing    
Links to Additional Documentation    
Release Notes    
What's New in this Release?    
Known and Fixed Issues    
How Do I Get Started?    
Installation Overview    
Before you Begin: System Requirements    
Installing tc Server: Typical Steps    
Overview of tc Server Directories, Variables, and Configuration Files    
Post-Installation Tasks    
Creating a New tc Server Instance    
Starting and Stopping tc Server Instances    
Starting and Stopping the AMS Server and Agents    
Getting Started with the AMS Console    
Deploying Applications to tc Server    
Uninstalling tc Server: Typical Steps    
Upgrade and Migration Guide    
Tutorial: Using AMS to Configure and Manage tc Server    
Tutorial: Very Simple Web Application Development    
Java Source of the Hello.java Servlet    
JSP Source for the hello.jsp JSP    
Sample web.xml File    
Sample Default index.html File    
Ant Build File to Compile and Package the Example    
Troubleshooting    


Getting Started with tc Server
SpringSource, IncGetting Started with tc ServerSpringSource tc Server
Introduction to tc Server
SpringSource tc Server is a Web application server based on open-source Apache Tomcat that preserves the best of Tomcat, well trusted by developers, and then adds the mission-critical operational capabilities that system administrators require but are currently unavailable in the open-source product.
These mission-critical capabilities include:
 
 
 
 
The following sections provide an overview of the SpringSource tc Server features. If, however, you already familiar with Apache Tomcat and want to see a detailed comparison between SpringSource tc Server and Apache Tomcat, see Differences Between tc Server and Apache Tomcat.
Tomcat Enhancements
The tc Server application server is based on the open-source Apache Tomcat server with additional usability improvments such as:
 
Improved out-of-the-box configuration of tc Server and the JVM installed with tc Server. This means that in the majority of cases, you can immediately start using tc Server right after you install it without having to perform any additional configuration.
 
Starting a tc Server instance is now easier and more intuitive for both UNIX and Windows.
 
A new configuration option enables high concurrency JDBC connection pool.
 
Ability to push configuration files to any local or remote location using command line utilities and to locally tune standard configuration files using catalina.properties.
Easy Configuration and Monitoring with SpringSource AMS
SpringSource Application Management Suite (AMS) is a comprehensive enterprise application management tool. It is designed to manage and monitor all instances of tc Server running on any computer, as well as all of your Spring-powered applications, and a variety of other non-SpringSource platforms and application servers such as Apache Tomcat. SpringSource AMS provides a single console with powerful dashboards that allow you to easily check the health of your applications. With SpringSource AMS, you can:
 
Manage the lifecycle of tc Server instances by starting, stopping, and restarting a local or remote server instance.
 
Similarly manage the lifecycle of a group of tc Server instances that are distributed over a network of computers.
 
Configure a single instance of tc Server. Configuration options include the various port numbers to which tc Server listens, JVM options such as heap size and enabling debugging, default server values for JSPs and static content, JDBC datasources, various tc Server connectors, and so on.
 
Deploy a Web application from an accessible file system, either local or remote. You can deploy to both a single tc Server instance or to a pre-defined group of servers.
 
Manage the lifecycle of applications deployed to a single tc Server or group of servers. Application lifecycle operations include start, stop, redeploy, undeploy, and reload.
All of the preceding tc Server-specific SpringSource AMS tasks are in addition to the standard AMS tasks :
 
Inventory the resources on your network.
 
Monitor those resources.
 
Alert on problems with those resources. AMS includes a pre-configured alert for deadlock detection in a running tc Server instance.
 
Control those resources.
Enhanced Diagnostics
SpringSource tc Server includes a full set of diagnostic features that makes it easy for you to troubleshoot any problems that might occur with tc Server or the applications that you deploy to tc Server. These diagnostic features include:
 
Deadlock detection: SpringSource tc Server automatically detects if a thread deadlock occurs in tc Server or an application deployed to tc Server.
 
Server dumps: In the event that a tc Server instance fails, the server automatically generates a snapshot of its state and dumps it to a file so that support engineers can recreate the exact state when diagnosing the problem.
 
Thread diagnostics: When you deploy and start a Web application on tc Server, 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. Although by default, tc Server logs these errors in the log files, it is often difficult to pinpoint where exactly the error came from and how to go about fixing it. By enabling thread diagnostics, tc Server provides additional information to help you troubleshoot the problem.
 
Time in Garbage Collection:: AMS has a new metric that represents the percentage of process up time (0 -100) in which tc Server has spent in garbage collection.
 
Tomcat JDBC DataSource monitoring: AMS includes a new service that represents the high-concurrency Tomcat JDBC datasources you have configured for your tc Server 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 most of the preceding diagnostics features, the AMS component of tc Server includes one or more pre-configured alerts which make it easy for you to monitor the tc Server 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 AMS alerts, see tc Server Administration Guide, and click Managing tc Server-Related AMS Alerts in the left frame.
tc Server Command-Line Interface
SpringSource tc Server provides a command-line interface (CLI) called tcsadmin that you can use to perform a subset of tc Server configuration and application deployment tasks. You can use the CLI to configure and manage both single tc Server instances or groups of tc Servers.
Some of the tasks you can perform using tcsadmin include:
 
List servers, groups, and deployed applications.
 
Deploy applications
 
Configure tc Server instances and groups
 
Control tc Server instances and groups
Differences Between tc Server and Apache Tomcat
SpringSource tc Server is an enterprise version of Apache Tomcat, the widely used Web application server. SpringSource tc Server is hardened for enterprise use and is coupled with key operational capabilities, advanced diagnostics, and is backed by mission-critical support.
SpringSource tc Server is designed to be 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 our customers to add the business-critical functionality they need to more effectively run and manage their applications with the least amount of effort.
The following sections list the additional features that SpringSource tc Server adds to standard Apache Tomcat.
Standard Application Server Features
The following table lists the standard application server features of both SpringSource tc Server and Apache Tomcat.
Application Server Features
SpringSource tc Server
Apache Tomcat
Servlet 2.5 Support
Yes
Yes
Java Server Pages (JSP) 2.1 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 Features
SpringSource tc Server is based on Apache Tomcat 6 and therefore provides a powerful yet lightweight platform that is compatible with existing Tomcat-based applications as well as 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 Server in order to gain the added benefits that SpringSource tc Server provides beyond the base Apache Tomcat.
The following table compares the enterpise features of SpringSource tc Server versus Apache Tomcat.
Additional Application Server Features
SpringSource tc Server
Apache Tomcat
Multiple runtime instances from a single binary installation
Yes
No
New high-concurrency JDBC connection pool`
Yes
No
Pre-configured for JMX management
Yes
No
Includes latest security vulnerability and bug fixes
Yes
Rebuild tomcat yourself to apply incremental fixes
Binary patch updates
Yes
Binary patches are not provided by Tomcat community
Unix boot scripts
Yes
No
Enhanced Windows service wrapper
Yes
No
The following table compares the advanced configuration features of SpringSource tc Server versus Apache Tomcat.
Advanced Configuration Features
SpringSource 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 data sources
Yes
No
Modify HTTP and AJP connector settings
Yes
No
Create and view general services
Yes
No
Modify general engine configuration
Yes
No
Pre-turned JVM options
Yes
No
Business-Critical Operational Features
SpringSource tc Server includes advanced, distributed management and monitoring capabilities via a centralized management console referred to as AMS (Application Management Suite).
The tables in this section list the capabilities that SpringSource tc Server provides over and above the base Apache Tomcat and also notes the features that AMS provides for existing Apache Tomcat environments.
SpringSource tc Server provides a wide range of capabilities that enable developers, administrators, and operators to centrally diagnose, measure, and monitor the distributed application infrastructure their applications are deployed on.
Diagnostics, Metrics, and Monitoring Features
SpringSource tc Server
Apache Tomcat
Application deadlock detection, including pre-configured deadlock trigger set to create heap and thread dumps with URL-to-thread association.
Yes
No
Uncaught exception detection, including heap/thread dumps
Yes
No
Garbage collection metrics including throughput and count
Yes
No
SQL query time monitoring metrics
Yes
No
Enhance reponse 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 AMS)
Automated inventory of application servers and software resources
Yes
Yes (via AMS)
Real-time metric collection and monitoring of tc Server, Tomcat, Apache Web server, Apache ActiveMQ, underlying JVM, operating system, and other resources
Yes
Yes (via AMS)
Historing charting and graphing performance
Yes
Yes (via AMS)
Advanced alerting: multi-conditional, availability, event, and recovery alerts, group-based alerting, and escalation schemes.
Yes
Yes (via AMS)
Log file tracing, alerts on event levels
Yes
Yes (via AMS)
Alerts based on configuration file updates
Yes
Yes (via AMS)
Performance baselining for alert thresholds
Yes
Yes (via AMS)
SpringSource tc Server provides a centralized, secure dashboard that enables administrators and operators to organize, operate, and control their distributed applications and infrastructure.
Centralized Operations and Management Features
SpringSource tc Server
Apache Tomcat
Secure, distributed, JMX-based server management
Yes
No
Create application server groups
Yes
Yes (via AMS)
Application server start/stop/restart from central console
Yes
Yes (via AMS)
List deployed applications and current status
Yes
No
Application deploy/undeploy/reload/start/stop
Yes
No
Security and access/authorization control
Yes
Yes (via AMS)
Scheduled control: maintenance activities, on-demand actions, scheduled remediation actions, or scheduled responses to alert conditions
Yes
Yes (via AMS)
SpringSource tc Server provides scripting support for administrators and operators who prefer to create and run scripts to handle distributed configuration and deployment steps.
Scripting Features
SpringSource tc Server
Apache Tomcat
List deployed servers
Yes
No
Create server groups
Yes
No
Add/delete servers to/from groups
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 JVM parameters from a server
Yes
No
Modify configuration files on an individual server
Yes
No
Se (push) configuration files and JVM parameters to a server group
Yes
No
Start, stop, and restart a server or group of servers
Yes
No
Supported Configurations
Supported Java EE Specifications
SpringSource tc Server supports the following Java EE specifications:
Supported JVM Versions
The following table lists the supported JVM versions for the three components of tc Server.
tc Server Component
Supported JVM Version(s)
Notes
tc Server Application Server
1.5, 1.6
Although the AMS agent and server are supported on Java 1.5 only, this does not preclude tc Server itself from running on Java 1.6. An AMS agent or server running on Java 1.5 is fully capable of managing a tc Server running on Java 1.6.
AMS Agent
1.5
AMS agents, by default, use a bundled Java 1.5 JVM. You can choose to run an AMS agent using a different JVM by setting the HQ_JAVA_HOME environment variable.
AMS Server
1.5
AMS servers, by default, use a bundled Java 1.5 JVM. You can choose to run an AMS server using a different JVM by setting the HQ_JAVA_HOME environment variable.
Supported Configurations: tc Server (Application Server Component)
The following table lists the supported configurations for running the application component of tc Server.
NOTE: Because you typically also install the AMS agent on the same computer as the tc Server itself, you should also consult Supported Configurations: AMS Agent.
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.
Operating System
Major Version
Chip Architecture
JVM
tc Server Version
RedHat Enterprise Linux (RHEL)
V4
x86 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.19.A, 6.0.20.A, 6.0.20.C
RedHat Enterprise Linux (RHEL)
V5
x86 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.20.A, 6.0.20.C
openSUSE
10
x86 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.20.A, 6.0.20.C
openSUSE
11
x86 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.20.A, 6.0.20.C
Windows
2008 Server
x86 64 bit
Sun Hotspot 1.5, 1.6
6.0.20.C
Windows
2003 Server SP1 and newer
x86 32 bit
Sun Hotspot 1.5, 1.6
6.0.19.A, 6.0.20.A, 6.0.20.C
Windows
2003 Server SP1 and newer
x86 64 bit
Sun Hotspot 1.5, 1.6
6.0.20.A, 6.0.20.C
Solaris
10
 
Sparc
 
Intel 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.19.A, 6.0.20.A, 6.0.20.C
AIX
5.3
PowerPC 32/64 bit
IBM JVM 1.5, 1.6
6.0.20.B, 6.0.20.C (see note)
AIX
6.1
PowerPC 32/64 bit
IBM JVM 1.5, 1.6
6.0.20.B, 6.0.20.C (see note)
Linux on System z (zLinux)
2.6
zSeries s390x 64 bit
IBM JVM 1.5, 1.6
6.0.20.B, 6.0.20.C (see note)
Mac OS
10.5
x86 32/64 bit
Sun Hotspot 1.5, 1.6
6.0.20.A, 6.0.20.C
Note (AIX): In versions 6.0.20.B and 6.0.20.C of tc Server, only the application server component is supported on the AIX platform; there is no managed-node bundle available for this platform. If you need to install or upgrade the application server on AIX, use the platform-independent bundle (called tcServer-6.0.20.C-GA-appserver.tgz.)
Note (zLinux): In version 6.0.20.C of tc Server, only the application server component is supported on the zLinux platform. There is no managed-node bundle available for this platform. If you need to install or upgrade the application server component on zLinux, use the platform-independent bundle (called tcServer-6.0.20.C-GA-appserver.tgz.)
Supported Configurations: AMS Agent
The following table lists the supported configurations for running the AMS agent.
NOTE: Because you typically also install the AMS agent on the same computer as the tc Server itself, you should also consult Supported Configurations: tc Server (Application Server Component).
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.
Operating System
Major Version
Chip Architecture
JVM
tc Server Version
RedHat Enterprise Linux (RHEL)
V4
x86 32/64 bit
Sun Hotspot 1.5
6.0.19.A, 6.0.20.A, 6.0.20.C
RedHat Enterprise Linux (RHEL)
V5
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
openSUSE
10
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
openSUSE
11
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
Windows
2008 Server
x86 64 bit
NOTE: The AMS agent binaries must run using a 32-bit JVM.
Sun Hotspot 1.5 (32 bit)
6.0.20.C
Windows
2003 Server SP1 and newer
x86 32 bit
Sun Hotspot 1.5
6.0.19.A, 6.0.20.A, 6.0.20.C
Windows
2003 Server SP1 and newer
x86 64 bit
NOTE: The AMS agent binaries must run using a 32-bit JVM.
Sun Hotspot 1.5 (32 bit)
6.0.20.C
Solaris
10
 
Sparc
 
Intel 32/64 bit
Sun Hotspot 1.5
NOTE: The AMS agent on Solaris (Intel) does not bundle its own JRE; all agents on other platforms do. This means that on Solaris (Intel), you must set the HQ_JAVA_HOME variable to point to the location of an installed JRE before you start the AMS agent.
6.0.19.A, 6.0.20.A, 6.0.20.C
Linux on System z (zLinux)
2.6
zSeries s390x 64 bit
IBM JVM 1.5
NOTE: As with AMS agents on all other supported configurations, the AMS agent on zLinux bundles the Sun Hotspot JRE 1.5. The bundled HotSpot JRE, however, does not work correctly with the AMS agent on zLinux. This means that you must set the HQ_JAVA_HOME variable to point to the location of an installed IBM JRE/JVM 1.5 (64-bit) before you start the AMS agent.
6.0.20.B
Mac OS
10.5
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
Supported Configurations: AMS Server
The following table lists the supported configurations for running the AMS server.
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.
Operating System
Major Version
Chip Architecture
JVM
tc Server Version
RedHat Enterprise Linux (RHEL)
V4
x86 32/64 bit
Sun Hotspot 1.5
6.0.19.A, 6.0.20.A, 6.0.20.C
RedHat Enterprise Linux (RHEL)
V5
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
openSUSE
10
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
openSUSE
11
x86 32/64 bit
Sun Hotspot 1.5
6.0.20.A, 6.0.20.C
Windows
2008 Server
x86 64 bit
NOTE: The AMS server binaries must run using a 32-bit JVM.
Sun Hotspot 1.5 (32 bit)
6.0.20.C
Windows
2003 Server SP1 and newer
x86 32 bit
Sun Hotspot 1.5
6.0.19.A, 6.0.20.A, 6.0.20.C
Windows
2003 Server SP1 and newer
x86 64 bit
NOTE: The AMS server binaries must run using a 32-bit JVM.
Sun Hotspot 1.5 (32 bit)
6.0.20.C
Solaris
10
Sparc
Sun Hotspot 1.5
6.0.19.A, 6.0.20.A, 6.0.20.C
Supported Browsers for Accessing the AMS Dashboard
The following table lists the supported browsers that you can use to access the AMS dashboard.
Browser
Supported Version(s)
Firefox
1.5.x, 2.0.x, 3.5
Safari
3, 4
Internet Explorer
7
Tested Configurations: tc Server (Application Server Component)
The following tables list specifically tested patch update levels for the latest 6.0.X version of tc Server (application server component.)
Operating System
Major Version
Chip Architecture (Tested)
Fully Qualified of JVM Version (Tested)
Version of tc Server (Tested)
RedHat Enterprise Linux (RHEL)
V4
x86 32 bit
 
Sun Hotspot 1.5.0_17 (32 bit)
 
Sun Hotspot 1.6.0_11 (32 bit)
6.0.20.C
RedHat Enterprise Linux (RHEL)
V5
x86 64 bit
 
Sun Hotspot 1.5.0_18 (64 bit)
 
Sun Hotspot 1.6.0_18-ea (64 bit)
6.0.20.C
openSUSE
10
x86 32 bit
 
Sun Hotspot 1.5.0_20 (32 bit)
 
Sun Hotspot 1.6.0_16 (32 bit)
6.0.20.C
openSUSE
11
x86 64 bit
 
Sun Hotspot 1.5.0_18 (64 bit)
 
Sun Hotspot 1.6.0_18-ea (64 bit)
6.0.20.C
Windows
2008 Server
x86 64 bit
 
Sun Hotspot 1.5.0_18 (32 bit)
 
Sun Hotspot 1.6.0_15 (64 bit)
6.0.20.C
Windows
2003 Server SP2
x86 32 bit
 
Sun Hotspot 1.5.0_18 (32 bit)
 
Sun Hotspot 1.6.0_13 (32 bit)
6.0.20.C
Windows
2003 Server SP2
x86 64 bit
 
Sun Hotspot 1.5.0_17 (64 bit)
 
Sun Hotspot 1.6.0_18-ea (64 bit)
6.0.20.C
Solaris
10
Sparc
 
Sun Hotspot 1.5.0_18 (32 bit)
 
Sun Hotspot 1.6.0_13 (32 bit)
6.0.20.C
Solaris
10
Intel 32 bit
 
Sun Hotspot 1.5.0_04 (32 bit)
 
Sun Hotspot 1.6.0_11 (32 bit)
6.0.20.C
AIX
5.3
PowerPC 64 bit
 
J2RE 1.6.0 IBM J9 2.4 AIX ppc64-64
 
J2RE 1.5.0 IBM J9 2.3 AIX ppc64-64
6.0.20.C
AIX
6.1
PowerPC 64 bit
 
J2RE 1.6.0 IBM J9 2.4 AIX ppc64-64
 
J2RE 1.5.0 IBM J9 2.3 AIX ppc64-64
6.0.20.C
Linux on System z (zLinux)
2.6
zSeries s390x 64 bit
 
J2RE 1.6.0 IBM J9 2.4 Linux s390x-64
 
J2RE 1.5.0 IBM J9 2.3 Linux s390x-64
6.0.20.C
Mac OS
10.5
x86 64 bit
 
Sun Hotspot 1.5.0_19 (32 bit)
 
Sun Hotspot 1.6.0_13 (64 bit)
6.0.20.C
Tested Configurations: AMS Agent
The following tables list specifically tested patch update levels for the latest 6.0.X version of tc Server (AMS agent component.)
Operating System
Major Version
Chip Architecture (Tested)
Fully Qualified JVM Version (Tested)
Version of tc Server (Tested)
RedHat Enterprise Linux (RHEL)
V5
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
RedHat Enterprise Linux (RHEL)
V4
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
openSUSE
10
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
openSUSE
11
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
Windows
2008 Server
x86 64 bit
Sun Hotspot 1.5.0_12 (32 bit)
6.0.20.C
Windows
2003 Server SP2
x86 32 bit
Sun Hotspot 1.5.0_12
6.0.20.C
Windows
2003 Server SP2
x86 64 bit
Sun Hotspot 1.5.0_12 (32 bit)
6.0.20.C
Solaris
10
 
Sparc
 
Intel 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
Linux on System z (zLinux)
2.6
zSeries s390x 64 bit
J2RE 1.5.0 IBM J9 2.3 Linux s390x-64
6.0.20.B
Mac OS
10.5
x86 32/64 bit
Sun Hotspot 1.5.0_19
6.0.20.C
Tested Configurations: AMS Server
The following tables list specifically tested patch update levels for the latest 6.0.X version of tc Server (AMS server component.)
Operating System
Major Version
Chip Architecture (Tested)
Fully Qualified JVM Version (Tested)
Version of tc Server (Tested)
RedHat Enterprise Linux (RHEL)
V4
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
RedHat Enterprise Linux (RHEL)
V5
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
openSUSE
10
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
openSUSE
11
x86 32/64 bit
Sun Hotspot 1.5.0_12
6.0.20.C
Windows
2008 Server
x86 64 bit
Sun Hotspot 1.5.0_12 (32 bit)
6.0.20.C
Windows
2003 Server SP2
x86 32 bit
Sun Hotspot 1.5.0_12
6.0.20.C
Windows
2003 Server SP2
x86 64 bit
Sun Hotspot 1.5.0_12 (32 bit)
6.0.20.C
Solaris
10
Sparc
Sun Hotspot 1.5.0_12
6.0.20.C
Restrictions and Licensing
Restrictions
The following restrictions apply to SpringSource tc Server:
 
The AMS Server and agents are supported only on JDK 1.5. AMS includes its own default JDK that the tc Server installation program automatically installs.
 
The heap and exception dump diagnostic feature works only with JDK 1.6.
 
If you want to run the AMS server or agent on a computer that is running JDK 1.6 to take advantage of the heap dump feature of tc Server, you must be sure that both versions of the JDK (1.5 and 1.6) are installed on your computer and set each appropriately. As mentioned above, AMS includes its own default JDK 1.5.
 
You can use the AMS application management features of tc Server only with the tc Server application server; these features do not work with standard Apache Tomcat. The AMS application management features include deploy, undeploy, start, stop, and reload of Web applications.
AMS Plug-Ins Licensed For Use With SpringSource tc Server
SpringSource Application Management Suite (AMS) provides powerful monitoring and management features and is a key component of SpringSource tc Server
SpringSource tc Server provides the license to use the following set of 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 Server, SpringSource dm Server, Apache Tomcat
 
Messaging Middleware: ActiveMQ
Links to Additional Documentation
Because the tc Server application server is based on Apache Tomcat, much of the documenation about using tc Server itself is provided by Apache.
The AMS 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 AMS console includes online-help for both generic AMS functionality, as well as tc Server related functionality. You can also consult the following for additional documentatin about AMS:
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:
Release Notes
The following sections contain release-specifc information about tc Server.
What's New in this Release?
This section describes the new and changed features for the following versions of tc Server:
6.0.20.C
The following features are new in version 6.0.20.C of tc Server.
 
Tomcat version: SpringSource tc Server uses version 6.0.20.C of Tomcat as its core.
 
Asynchronous Logging: You can configure that tc Server perform its logging asychronously, which means that the thread that writes to the log file is different from the thread that handles the incoming request. See tc Server Administration Guide, then click Configuring Asychronous Logging in the left frame.
 
Templates: When you create a new tc Server instance, you can use the new -t (--template) option to specify a template. Templates contain customized and additional tc Server files. Applying a template to a new instance customizes it beyond the standard Tomcat instance. See Creating a tc Server Instance Using a Template for details.
 
Silent Installation: If you are installing a managed node or just the application server component of tc Server, you can pass the installation script properties rather than install interactively. This feature is not available when installing the full tc Server distribution (AMS server, AMS agent, and application server.) See Silently Installing a Managed Node or Application Server for details.
 
Open Sessions Count: The AMS console and tcsadmin list-applications CLI command now display the number of active sessions for each deployed application.
 
Encrypting Passwords: You can now encrypt the password in the conf/jmxremote.password file. See tc Server Administration Guide, then click Encrypting Passwords in tc Server Configuration Files in the left frame.
 
New options of the tcserver-instance.sh|bat script: The tcserver-instance.sh|bat script has the following new options:
 
--list: Lists the known tc Server instances for a particular installation.
 
--ports: Used to specify the four port numbers of the server.xml file.
 
New options of the tcserver-ctl.sh|bat script: The tcserver-ctl.sh|bat script has the following new options:
 
batch: (Windows only) Runs the tc Server instance using the catalina.bat script as a batch job.
 
restart: Restarts a running tc Server instance.
 
install run-as-user: (Windows only) Optionally specify the user account that is used to start the tc Server Windows service.
 
New option of the tcsadmin put-file command: The put-file command of the tcsadmin script has a new option: --nobackupfile. This option prevents the script from creating a backup of the new configuration file it is pushing to the tc Server instance, which is the default behavior of the command. See tc Server Administration Guide, then click The tc Server Command Line Interface in the left frame.
The following features changed in version 6.0.20.C of tc Server.
 
The ServiceabilityLifecycleListener has been removed from the default conf/server.xml file and relevant sample files in the conf/samples. SpringSource tc Server now uses the JVM when detecting deadlocks and generating server dumps.
 
You no longer have to be the AMS administration user to configure tc Server and deploy applications using the AMS GUI and the tcsadmin CLI. Rather, any AMS user who has been given the correct permissions can perform these tasks.
6.0.20.B
The following features are new in version 6.0.20.B of tc Server.
 
Tomcat version: SpringSource tc Server uses version 6.0.20.B of Tomcat as its core.
 
Supported Configurations: SpringSource tc Server supports the following new platforms : AIX 5.3/6.1 and Linux on System z (zLinux) 2.6. See Supported Configurations for details.
6.0.20.A
The following features are new in version 6.0.20.A of tc Server.
 
Tomcat version: SpringSource tc Server uses version 6.0.20.A of Tomcat as its core.
 
New options of the tcserver-instance.sh|bat script: The tcserver-instance.sh|bat script has the following new options:
 
-m: Modifies the tc Server version of an existing instance.
 
-n: Specifies an alternate home directory for the new instance.
 
-r: Specifies the location of the JRE.
 
Password Encryption in XML files. You can now encrypt passwords in the server.xml, context.xml, and web.xml files. See tc Server Administration Guide, then click Encrypting Passwords in tc Server XML Files in the left frame.
 
Sample boot.rc file: The sample boot.rc.template file is for Unix administrators who want tc Server instances to start automatically when their Unix system boots up. See Starting and Stopping tc Server Instances.
 
Oracle proxy connection authentication: You can now configure an Oracle global datasource to use proxy authentication. See tcServer Administration Guide, then click Configuring an Oracle DataSource With Proxied Usernames in the left frame.
 
Upgrade and Migration Guide: Describes how to upgrade a tc Server instance to the latest release and how to migrate an ERS 4.0 instance to tc Server. See Upgrade and Migration Guide for details.
The following changes occurred in version 6.0.20.A of tc Server.
 
The name of the tc Server installer program on all supported platforms is now called install.sh (Unix) or install.bat (Windows), rather than the previous run.sh|bat.
 
SpringSource tc Server is now distributed in three different packages, based on the components you want to install and the components that are supported on a particular platform. One of the packages is platform-neutral and includes only the application server itself. This option presents a more streamlined download to users interested in using only the tc Server application server. See Installing tc Server: Typical Steps.
 
Sample server-XXX.xml files are now located in the CATALINA_HOME/conf/samples directory of a tc Server instance.
 
The error messages of the tcserver-instance.sh script have been improved for better usability.
 
The documentation has been updated to include a section on configuring the AMS server to use a trusted certificate rather than the default self-signed certificate. See the tc Server Administration Guide, then click Securing the AMS Server in the left frame.
Known and Fixed Issues
The following table lists the known issues in SpringSource 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 applicable, the version in which it was fixed. If there is no version listed in the Fixed In column, the issue is still open. The open issues are grouped according to the version in which they were found, with the most recent ones listed first. The fixed issues are listed at the end of the table.
The ID of a particular known issue indicates the engineering component to which the issue belongs; in particular:
 
TCSRV-XXX: The tc Server product as a whole.
 
AMS-XXX: The AMS Server or Agent components.
 
HQ-XXX: Hyperic HQ, the core of the AMS components.
NOTE: In version 6.0.19.A of tc Server, all known issues were identified with keys of the form TCSRV-XXX, where XXX is an integer. However, after SpringSource released version 6.0.19.A of tc Server, the AMS-related tc Server issues were migrated to different internal issue trackers. This migration caused the keys of these existing issues to change to either AMS-XXX or HQ-XXX. Where applicable, the following table has been updated to reflect the new keys for these existing issues; they are shown in parentheses next to the old issue key. Additionally, completely new issues that relate to the AMS components use either the AMS-XXX or HQ-XXX key; the TCSRV-XXX key now corresponds to the tc Server product as a whole.
Issue ID
Description
Found In
Fixed In
AMS-254
When the AMS component parses the setenv.sh file of a particular tc Server instance, it incorrectly appends the values of multiple JVM_OPTS variables rather than taking the last entry as being the actual value. For example, if the setenv.sh file includes the following:
JVM_OPTS="-server -Xms512m" JVM_OPTS="-Xmx1024m"
the AMS component thinks the JVM_OPTS variable is set to -server, -Xms512m, -Xmx1024m rather than the correct -Xmx1024m.
Workaround: Include only one JVM_OPT variable in the setenv.sh file.
6.0.20.C
 '
AMS-265
If the value of the JVM_OPTS variable in the setenv.sh file of a particular tc Server instance is not enclosed in quotes, the AMS console does not display the option in the singler server configuration page and the tcsadmin script does not display the value when you run the get-jvm-option command.
Workaround: Enclose the value of JVM_OPTS in the setenv.sh file in quotes.
6.0.20.C
 '
AMS-316
The add-server command of the tcsadmin script accepts only a group name, and not a group id. This is inconsistent with the other commands that take either a group name or group id.
6.0.20.C
 '
AMS-494
When using the AMS console to deploy a WAR file and the disk runs out of space, the error message displayed by the AMS console is unhelpful:
rhl.localdomain tc Server Test_Two (10417) had failure(s). Failure - null.
Workaround: Check the tc Server application log file because it provides a better error message in this case: java.io.IOException: No space left on device.
6.0.20.C
 '
AMS-557
If a user uses the AMS console to configure a Connector with SSL, the AMS component generates a server.xml that mixes attributes between the Java connectors and the APR connectors, resulting in an invalid configuration.
For example, the resulting <Connector> element contained both the SSLxxx attributes (used by the APR connector) and keystoreFile (used by the Java connector).
Workaround: Edit the server.xml directly when configuring a Connector with SSL.
6.0.20.C
 '
AMS-670
When you click the ? symbol in the top-right corner of the AMS console login screen, you get the following error:
The page requested cannot be displayed due to some error. You can view the stack trace, Return to the previous page, Dashboard, or Browse Resources page..
Clicking the stack trace link shows nothing, nor do the log files.
6.0.20.C
 '
AMS-671
Users are unable to login to the AMS console using the guest account, even when the account is explicitly enabled.
Workaround: Use a different AMS user's account.
6.0.20.C
 '
AMS-672
When choosing the Upgrade AMS Server option of the install.sh installer program, the default value of the full pathname of the AMS server to upgrade is an empty string rather than an attempted guess at the pathname.
6.0.20.C
 '
AMS-682
If you upgrade the AMS server to the version included in 6.0.20.C, restart it, then try to use the AMS console to change the JMX port number of a new or existing tc Server instance, the change is reflected on the AMS configuration screen, but the change does not trigger an auto-discovery of the modified tc Server instance. For this reason, the configuration change does not propagate correctly to all of the AMS server, resulting in problems such as not being able to view the deployed applications.
6.0.20.C
 '
AMS-683
In certain cases, if you upload a badly formatted configuration file to the AMS server, which in turn causes a restart of the server to fail, an undo of the upload might not work, which means subsequent starts of the AMS server will continue to fail.
Workaround: Replace the corrupt configuration file with a correct one manually.
6.0.20.C
 '
TCSRV-848
(Windows only). If you upgrade a tc Server instance on Windows from version 6.0.20.A to 6.0.20.C using the -m (--modifyver) option of the tcserver-instance.bat script, you will not be able to then start the instance; instead, you will get the following error:
java.lang.NoClassDefFoundError: org/apache/juli/logging/LogFactory
Workaround: Add the following two lines to the CATALINA_BASE/conf/wrapper.conf file of your upgraded tc Server instance:
wrapper.java.classpath.3=%CATALINA_BASE%\bin\tomcat-juli.jar wrapper.java.classpath.4=%CATALINA_HOME%\bin\tomcat-juli.jar
6.0.20.C
 '
TCSRV-522
If you run the tcserver-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.
6.0.20.A
 '
TCSRV-152 (AMS-319)
If you use the AMS_SERVER_HOME/bin/db-stop.sh script to stop the built-in database used by the AMS server, the AMS server continues to run in the background, although it is not apparent. If you later try to start the AMS server using the ams-server.sh start command, you will get an error.
Workaround: You should not use the db-stop.sh command to stop the built-in database by itself. Rather, always use the ams-server.sh start|stop commands which also start/stop the built-in database.
6.0.19.A
 '
TCSRV-169 (HQ-82)
In AMS, if you rename an already-discovered resource, AMS will "rediscover" it 15 minutes later and it will show up in the Auto Discovery portlet, listed as "Name Changed." AMS does not allow you to subsequently skip the resource, and thus you will not be able to get it out of the Auto-Discovery portlet.
Workaround: Leave the resource in the Auto-Discover portlet undisturbed.
6.0.19.A
 '
TCSRV-200 (HQ-1765)
Because tc Server instances always include a date in the name of the localhost.<date>.log file, and then roll over the file every day, you cannot easily use the AMS log file tracking feature on the localhost log file because you would have to change the name of the file every day.
6.0.19.A
 '
TCSRV-249 (HQ-1758)
If you try to make configuration changes to tc Server using the AMS console when tc Server is not running, you will get the following error: The configuration has not been set for this resource due to : Invalid configuration: Error contacting resource: Can't connect to MBeanServer....
Workaround: Be sure tc Server has been started before trying to update its configuration using AMS.
6.0.19.A
 '
TCSRV-257 (HQ-1743)
If you use the AMS_SERVER_HOME/bin/db-start.sh script to manually start the built-in database used by the AMS server, you get the message WARNING: Unable to create restricted tokens on this platform, but then no further status message telling you whether the database started or not.
Workaround: You should not use the db-start.sh command to start the built-in database. Rather, always use the ams-server.sh start command which starts both the AMS server and the built-in database.
6.0.19.A
 '
TCSRV-280 (HQ-1747)
If you try to stop the AMS server by running the ams-server.sh stop command as the root user, rather than the user who started and thus owns the AMS process, you get an error. The AMS process then hangs and must be killed manually.
Workaround: Always run ams-server.sh stop as the actual user who owns the AMS process.
6.0.19.A
 '
TCSRV-369 (HQ-1748)
The AMS Agent log can contain extraneous messages of the form 2009-03-09 11:39:46,281 DEBUG [Galert Event Listener1] [org.hyperic.hq.galerts.processor.MemGalertDef.Fired] Alert def [Memory] with id=10002 firing ; you can safely ignore these messages.
6.0.19.A
 '
TCSRV-384 (AMS-302)
Version 8 RC1 of Windows Internet Explorer returns Javascript errors if you try to use it with the tc Server Configuration pages in AMS.
Workaround: Use a non-Beta version of IE, such as version 7.
6.0.19.A
 '
TCSRV-394 (AMS-292)
In AMS, if you run an AMS agent on a computer that uses the IBM JDK/JRE, you will not be able to gather metrics on Percept Up Tim in Garbage Collection for the tc Server instance running on that computer. Additionally, the AMS console displays the message This resource is turned off or has not been configured properly.
Workaround: Use the JDK/JRE provided by Sun rather than the one provided by IBM.
6.0.19.A
 '
TCSRV-397 (HQ-1720)
In AMS, if you execute a control action on a group of tc Servers, a link appears next to the Command State field that says View Details. The expected behavior if you click on the link is for the page to automatically update when the command has completed; however, the page does not automatically update.
Workaround: Click back to the previous AMS console page to see if the command actually succeeded or failed.
6.0.19.A
 '
TCSRV-399 (HQ-1757)
The tc Server installer includes a misleading message about the reason for running a script in a separate window as the root user (called root script for simplicity.) The message does not mention that the script, in addition to setting shared memory settings, also sets up the required file permissions on the scripts used to run the AMS server. As a result, some users might think they do not need to run the root script, in which case the required scripts will have the incorrect permissions.
Workaround: Be sure you always run the root script when installing tc Server.
6.0.19.A
 '
TCSRV-400 (HQ-1743)
AMS does not discover a tc Server instance (in ASF layout) if it was started as a JSVC (commons daemon).
Workaround: Start a tc Server instance using the tcserver-ctl command script.
6.0.19.A
 '
TCSRV-407 (HQ-2777)
If you rename a tc Server instance and then trigger an auto-discovery, AMS discovers a whole new set of services that start with the name of the new tc Server instance. Conceptually these are exactly the same services as those associated with the old name of the tc Server instance, but now there are 2 copies. The old ones remain but show as Unavailable.
Workaround: Ignore the services with old names and work only with the new ones.
6.0.19.A
 '
TCSRV-412 (AMS-248)
If you try to run the tcsadmin command-line interface against an AMS server that is still in the process of starting, you get a misleading error message of the form DefaultValidationEventHandler: [FATAL_ERROR]: unexpected element (uri:"", local:"html"). rather than a more user-friendly message that says the AMS server is still starting. You can safely ignore this error.
Workaround: Wait to run the tcsadmin command-line interface until the AMS server has fully started.
6.0.19.A
 '
TCSRV-420 (HQ-2128)
The first time you start the AMS agent after installing it, the start script asks you for the port to which the AMS agent process listens. If you enter a number other than the default (2144), the AMS agent will not be correctly configured, although the script and startup of the agent do not return an error.
Workaround: Manually edit the agent.properties file, located in the top-level AMS agent installation directory, and add the following line:
agent.listenPort=XXXX
where XXXX refers to the agent's listen port.
6.0.19.A
 '
TCSRV-429 (AMS-294)
In certain situations, if you log out of the AMS console but leave the browser window open, then hours later try to log back in using the same browser window, you might get the following error:
java.lang.NullPointerException at org.hyperic.hq.ui.action.portlet.resourcehealth.ViewAction.execute(ViewAction.java:79)
Workaround: Log into the AMS console using a new brower window.
6.0.19.A
 '
TCSRV-478 (AMS-287)
AMS does not support configuring data sources for the tc Server-specific com.springsource.tcserver.serviceability.request.DataSourceFactory. This factory extends the Tomcat data source factory.
6.0.19.A
 '
TCSRV-481
If you try to run the tc Server installer from a directory that does not have write permissions (i.e. is read-only), the installation fails.
Workaround: Change the permissions on the read-only directory so that it is also writeable, or move the tc Server installer program to a writeable directory.
6.0.19.A
 '
TCSRV-485 (AMS-317)
This issue applies only to using the tcsadmin command-line interface against a group of tc Servers in which at least one instance is running on a Windows platform and another is running on a Unix platform. If you use the put-file command and use back slashes to specify the location of the file, the tc Server instance that is ruuning on Unix interprets the back-slash as part of the file name rather than converting it into a forward slash. This results in the tc Server instance on Unix creating a file called conf\server.xml rather than creating a file called server.xml in the directory conf.
Workaround: When using tcsadmin against a group of tc Servers in which some run on Windows and others run on Unix, be sure to always use forward-slashes when specifying a file's location.
6.0.19.A
 '
TCSRV-521 (AMS-300)
AMS does not auto-discover, and thus does not monitor, globally-defined DBCP datasources. Globally defined means configured in the server.xml file or using the AMS Views > Server Configuration page.
Workaround: If you require monitoring of datasources, use the high-concurrency SpringSource datasource.
6.0.19.A
 '
AMS-486
This issue applies when running the AMS console on a 3.5.X version of Firefox that is branded or code-named Shiretoko on Ubuntu Linux. It may also apply to other branded versions of Firefox, if the user agent string sent out by the browser reflects another brand name instead of Firefox.
Ubuntu users who upgrade to Firefox 3.5 using the package manager, for example, might get this version of Firefox. The browser window title bar text will list Shiretoko instead of Mozilla Firefox at the end, but to definitively check whether you are using a Shiretoko or other branded version of Firefox, go to Help > About Mozilla Firefox and check the identifying user agent string; it will include the string Shiretoko towards the end, instead of the normal Firefox.
When you run the AMS web console in the environment described in the preceding paragraphs, if you update a configuration page that includes a multi-line text box (such as the Server Start Configuration page) and then save your changes, the multi-line text box contents is replaced with the word undefined, even if you have not touched the text box itself. This typically produces an invalid tc Server configuration. In the case of the Server Start Configuration page, the word undefined is added to the JVM startup options, which in turn prevents the tc Server instance from starting up successfully.
Workaround: The following workaround applies to Firefox browsers branded Shiretoko, or any name other than Firefox:
1.
 
Type the text about:config in the address bar of your Firefox browser.
2.
 
Click the I'll be careful, I promise button on the warning page.
3.
 
Use the Filter text box at the top of the page to search for the string general.useragent.extra.firefox. If you are running into this issue, the value of this preference will be something like Shiretoko/3.5.2.
4.
 
Double-click on the preference in the table, and enter Firefox/3.5.2 in the field.
5.
 
Click OK.
6.
 
Reload the tc Server configuration AMS screen to see your change in action.
The AMS console should now work correctly.
Note that if you upgrade your browser to a new version (for example, from 3.5.2 to 3.5.3), the general.useragent.extra.firefox value will most likely reset back to the default; in which case, you will have to change it again using the preceding procedure.
6.0.20.A
6.0.20.C
AMS-496
The AMS agent on Windows (which currently is supported to run only in a 32 bit JVM) does not properly auto-discover, control, or report availability of a tc Server 6.0.20.A running with 64 bit wrapper and JVM on Windows.
6.0.20.A
6.0.20.C
TCSRV-600
When using the AMS console, the currentThreadCount and currentThreadsBusy attributes of a particular Executor Mbean (for example, the one associated with the default HTTP connector listening at port 8080) do not reflect the actual current thread metrics. The tc Server instance itself is correctly gathering these metrics; the issue is that the AMS console is not displaying them correctly.
6.0.20.A
6.0.20.C
TCSRV-641
Installing tc Server on Solaris (Sparc) sometimes fails when the installer is checking for a compatible tar command. The failure is sporadic.
Workaround: Because the failure is inconsistent, re-running the installation often succeeds.
6.0.20.A
6.0.20.C
TCSRV-416 (AMS-208)
If you create two tc Server instances in which the installation path of one is the complete substring of the other (for example, /home/tcServer-6.0/myserver and /home/tcServer-6.0/myserver1), start myserver1 but not start myserver, the AMS server still shows the stopped myserver instance as Available.
Workaround: Do not create a tc Server instance whose installation path is a complete substring of another instance.
6.0.19.A
6.0.20.C
TCSRV-456 (AMS-295)
When using the tcsadmin command-line interface, only users with explicit AMS super-user privileges are allowed to use the application management and server configuration commands.
Workaround: Run the commands as the AMS super-user.
6.0.19.A
6.0.20.C
TCSRV-467
If you make changes to files in the installed Apache Tomcat directory (INSTALL_DIR/tcserver-6.0/tomcat-6.0.19.A) and then use the INSTALL_DIR/tcServer-6.0/tcserver-instance.sh script to create a new tc Server instance that uses the SpringSource directory layout, the new tc Server instance might include some of the changes you made to the Apache Tomcat directory. For example, a listing of the applications deployed to the new tc Server instance might include manager and host-manager, even though you have not explicitly deployed them to the new server instance.
6.0.19.A
6.0.20.C (Use new templating feature)
TCSRV-691
When attempting to start the tc Server application server component on AIX using version 1.5 of the JDK, an exception is thrown resulting in the server not starting.
Workaround: Use version 1.6 of the JDK. If you must use version 1.5 of the JDK, you can also workaround this problem by commenting out the following lines in the conf/catalina.properties file:
#org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.springsource.tcserver.security.PropertyDecoder
#com.springsource.tcserver.security.PropertyDecoder.passphrase=springsource
6.0.20.A
6.0.20.B
TCSRV-330
If you run the tc Server installer program as the root user (which you should not do), and try to install the AMS components, the installer program correctly returns an error, but then incorrectly instructs you to re-run the ams-setup.sh program as a different user.
Workaround: Do not run the tc Server installer program as the root user.
6.0.19.A
6.0.20.A
TCSRV-380
The tc Server DataSource MBean ObjectNames are re-generated each time tc Server is restarted. For this reason, after you restart the tc Server application server component, the AMS Server thinks an existing tc Server Datasource is actually new and marks the old one as Unavailable, even though the "new" and "old" DataSource are actually the same thing. Additionally, AMS may not actually discover the new one until the next auto-discovery, which could be 24 hours by default.
Workaround: If you use the high-concurrency tc Server DataSource and have restarted tc Server, and want to then manage the DataSource in AMS, force an auto-discovery of the tc Server services so that the existing DataSource is marked as Available.
6.0.19.A
6.0.20.A
How Do I Get Started?
This section describes, from beginning-to-end, the high-level steps you must 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 AMS (the graphical interface for configuring and managing a tc Server instance or group of servers).
The steps are broken up into three high-level conceptual sections, as follows:
1.
 
2.
 
3.
 
Installing tc Server and Creating a New Server Instance
The installation of tc Server can be broken down into the installation of its three components: the tc Server application server (also called tc Server for simplicity), the AMS server, and the AMS agents. You can install all components on the same computer or on multiple computers.
Typically, you install just a single AMS server. You can install the tc Server application server on one or more computers; on each server you can then create multiple instances. Then, for each computer on which you have installed the tc Server application server component, you also install an AMS agent so that you can manage all the tc Server instances using the single AMS server. See Installation Overview for additional details.
SpringSource tc Server is distributed as three different types of ZIP or TAR files, depending on the components you want to install on a particular computer, as well as what is supported on a particular platform, such as RedHat Linux or Solaris. The three types of ZIP or TAR files are as follows:
 
The largest distribution includes all three components: AMS server, AMS agent, and tc Server application server, for a particular platform.
 
The next distribution includes just the AMS agent and the tc Server application server for a particular platform. If you install just these two components on a computer, the computer is called a managed node.
 
The smallest distribution includes just the tc Server application server. This distribution is platform-independent, which means you can use this distribution to install just the application server on any supported platform.
See Supported Configurations for details on what components are supported on what platforms.
The installation scripts in each type of ZIP or TAR file are very similar; the main difference between the install scripts on different distributions is that different components are listed as being available to install. Depending on how you want to configure tc Server, you download the appropriate distribution, then install some components, such as the AMS agent and a tc Server instance, on one computer, and the AMS server on another.
NOTE: It is assumed in this section that you are installing tc Server for the first time. If, however, you have already installed a previous version of tc Server and created one or more tc Server instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide for detailed information about the upgrade process.
In sum, this high-level installation step includes the following sub-steps:
1.
 
Install the tc Server application server on one or more computers.
See Installing tc Server: Typical Steps for detailed installation instructions.
2.
 
Install the AMS Server once.
See Installing tc Server: Typical Steps for detailed installation instructions.
3.
 
On each computer on which you installed the tc Server application server, install an AMS agent.
See Installing tc Server: Typical Steps for detailed installation instructions.
4.
 
Decide which directory layout you are going to use for the tc Server application server; your choices are SpringSource or ASF. See Differences between the SpringSource and ASF Layouts of tc Server for detailed information about the two possible layouts, the benefits of each one, what the directories look like, and what each directory contains.
5.
 
If you're using the SpringSource directory layout of the tc Server application server, you must create a new server instance. If you're using the ASF layout, a default server instance already exists and so you do not need to create one.
Starting the Components and Doing Initial Configuration
After you have installed tc Server, you must start the components. Depending on how you have configured tc Server, you will perform the following sub-steps on the computers on which you have installed the particular components.
1.
 
Start the tc Server instance(s) on each computer on which you installed tc Server.
2.
 
Start the AMS server on the computer on which you installed it.
3.
 
Start the AMS agent on all computers on which you installed it. Typically these are the same as the computers on which you installed and started the tc Server instances.
4.
 
Invoke the AMS Console in your browser, log in, and be sure it is configured for you to start managing tc Server instances.
Exploring the Features of tc Server
After you have started all the components of tc Server and have logged into the AMS console and have added the tc Server instances to the AMS inventory, you are now ready to explore the features of tc Server.
1.
 
Run through the AMS tutorial which describes typical tc Server tasks, such as deploying applications, configuring servers, and creating and using AMS groups.
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.
3.
 
If you want to deploy existing Web applications without using AMS, you can use static deployment.
4.
 
Learn about more advanced administration tasks, such as creating and using tc Server clusters and using the tc Server command-line interface by reading the tc Server Administration Guide
Installation Overview
Because tc Server is made up of a variety of components that can be hosted on different computers, the procedure for installing tc Server differs depending on your own scenario. SpringSource tc Server is made up of the following components that can be installed separately on different computers:
 
tc Server Application Server. In the documentation, this component is often listed as tc Server for simplicity. tc Server includes two "flavors" of the tc Server application server, based on the directory structure: ASF and SpringSource. See Differences between the SpringSource and ASF Layouts of tc Server.
 
Application Management Suite (AMS) server
 
AMS agent
Note: Not all components are supported on all platforms; see Supported Configurations for details.
The simplest scenario is where you install all components on the same computer. In this case, the computer acts as a host for the tc Server application server and its deployed applications as well as a host to the AMS server and agent used to manage the tc Server and its deployed applications.
Figure 1. Installing on One Computer
 
In the preceding figure, AMS is managing just one tc Server instance. AMS can, of course, manage multiple instances, as well as manage other kinds of servers. Note that, because the tc Server instance are all on one computer, you only need to install one AMS agent.
Figure 2. Multiple tc Server Instances on One Computer
 
A slightly more complicated scenario is where you install multiple tc Server instances on one computer, say computerA, and the AMS server on computerB. In this case, you must install the AMS agent on computerA so that the AMS server is able to manage the tc Servers on computerA from computerB. SpringSource refers to computerA as a managed node.
Figure 3. Installing on Two Computers
 
Another scenario is where you continue to host the AMS server on computerB, but want to install tc Server application servers on many computers, possibly of different platforms such as Unix and Windows. In this case you must also install the platform-appropriate AMS agent on each computer (managed node) that hosts the tc Server 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 Servers installed, but only one AMS agent. In the figure, all computers exceptcomputerB are managed nodes.
Figure 4. Installing on Multiple Computers
 
Before you Begin: System Requirements
This section includes the following topics that discuss system, software, and configuration requirements. Read this section before you begin the tc Server installation.
General System Requirements
SpringSource recommends the following system requirements for the computer on which you install the AMS server.
The AMS Server maintains an overall database representing metrics and configuration information collected from all associated AMS Agents over time. Therefore, the capacity of the underlying hardware, database, storage system and operating system needs to scale with the size of your deployment. The following additional configuration settings are recommended.
 '
Recommended for Evaluation - Smaller Deployments ( < 25 agents)
Recommended for Production - Medium to Large Deployments ( > 25 agents)
Processor
1x1 GHz x86
2x2 GHz x86 64 bit (32 bit for Windows)
Memory
1 GB
4 GB
Free Disk Space
1 GB
5 GB
Database
Embedded
Separate DBMS running on remote host:
 
MySQL 5.0.45+
 
Oracle 9i or 10g
 
PostgresSQL 8+
Required Software
Before you install tc Server, you must download and install a Java Development Kit (JDK) or Java Runtime Environment (JRE) on each computer on which you install one or more components of tc Server. See Supported Configurations for platform-specific details of the JDK/JRE versions you should install.
For most platforms you can download and install the Sun JDK/JRE, although for IBM computers you might want to install the IBM-specific JDK/JRE. The following links point to download Web sites:
Required System Configuration
Before you begin the tc Server installation, be sure to set the JAVA_HOME environment variable to point to your installed JDK/JRE. Additionally, be sure you update your PATH environment variable to point to the JAVA_HOME/bin directory.
Installing tc Server: Typical Steps
This topic contains the following sections:
NOTE: It is assumed in this section that you are installing tc Server for the first time. If, however, you have already installed a previous version of tc Server and created one or more tc Server instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide for detailed information about the upgrade process.
Overview of Installation
SpringSource tc Server is distributed in three different ZIP or TAR files, each containing a different combination of components. See Installing tc Server and Creating a New Server Instance for detailed information about what each distribution contains. Note that to install just the AMS server, you must download the entire distribution.
The naming convention for these distribution files is as follows:
 
The full distribution is called tcserver-version-GA-platform.tgz, where version refers to the version of tc Server and platform refers to the operation system, such as tcserver-6.0.20.C-GA-linux32.tgz or tcserver-6.0.20.C-GA-solaris-sparc.tgz. Windows distribution files have a sfx.jar extension rather than tgz.
 
The distribution that contains just the application server and AMS agent components (managed node) is called tcserver-version-GA-platform-node.tgz.
 
The distribution that contains just the tc Server application server is platform-independent and is called tcserver-version-GA-appserver.tgz.
The installation scripts in each distribution are essentially the same; the only difference is in the components that are available for you to install.
The preceding distribution files each include an installation script (install.sh on Unix and install.bat on Windows). SpringSource also distributes the underlying Tomcat server in a file that does not contain an installation script but rather is just a self-extracting JAR bundle; this file is called tcServer-version-tomcat.sfx.jar. It is assumed in most of this section that you are installing from a file that contains an installation script; if, however, you want to simply extract the underlying Tomcat server, see Installing Tomcat Server Using the Self-Extracting JAR File for additional information.
After you have decided which tc Server components you are going to install on your computer(s), you download the appropriate distribution to that computer. As described in Installation Overview, the two typical scenarios are as follows:
 
Install all components on the same computer. In this case, download the distribution that contains all components. Or
 
Install AMS server on one computer and then install the AMS agent and tc Server application server on another computer. In this case, download the full distribution to the first computer, but install only the AMS server. Then download the managed node distribution to the second computer and install both available components.
The typical installation procedure describes how to interactively install tc Server for both standard scenarios. The procedure covers both Unix and Windows installation, although the instructions are for Unix. If you are installing on Windows, change the forward slashes (/) to back slashes (\); other differences in the installation are called out.
If you are installing either a managed node (AMS agent and application server) or application server only, you can also install silently by passing properties to the install.sh or install.bat script. This feature, however, is not available when installing a full distribution (AMS server, AMS agent, and application server.) For details about silent installation, see Silently Installing a Managed Node or Application Server.
Tip: The installation of the AMS components of tc Server follows the generic AMS installation procedure; for complete documentation, see the SpringSource AMS Manual.
The tc Server installer program is supported on versions 1.5 and 1.6 of the JDK.
Important Note When Installing on Unix Platforms
The tc Server installer program requires a GNU compatible tar. This means that, before installing tc Server on a Unix platform, you must ensure that the tar command on your computer is compatible with the one required by the tc Server installer program. To do this, open a terminal window and run the following command:
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, you must ensure that the tc Server installer program can find the gtar executable by updating the PATH environment variable (either of the user running the tc Server installer program 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.
Interactive Installation Procedure: Typical Steps
NOTE: It is assumed in this section that you are installing tc Server for the first time. If, however, you have already installed a previous version of tc Server and created one or more tc Server instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide for detailed information about the upgrade process.
Follow these steps to interactively install tc Server:
1.
 
Read Before you Begin: System Requirements to ensure that you have the correct required system configuration and software before you begin the installation.
2.
 
Download the appropriate tc Server distribution from the SpringSource Download Center.
3.
 
Unzip or untar the tc Server distribution file into a temporary directory. Be sure the owner of the temporary directory is the same as the user that unzips/untars the distribution file, or you will get an error when you run the installer program.
On Windows, the distribution is a self-extracting JAR file that you can expand using Windows Explorer by double-clicking on it; the file unzips in the same directory in which it is located. NOTE: Internet Explorer recognizes that the downloaded distribution file is actually formatted as a ZIP file, and by default might change its file extension from .jar to .zip. This means that if you used IE to download the distribution file and its file extension changed, you might not be able to simply double-click on it to extract its contents. If this is the case, you can either use a zip extractor program, such as 7-Zip, to extract the files, or rename the file to have a .jar extension.
On Unix, use the tar command to extract the files. For example, to untar the file in the current directory and assign the extracted files to the same group as the user executing the command:
prompt$ tar --no-same-owner -xvzf /home/tarfiles/tcserver-6.0.20.C-GA-linux32.tgz
4.
 
Start a command prompt (Windows) or a terminal (Unix.)
5.
 
64-bit Unix platforms only. If you are installing tc Server on a 64-bit computer, you must explicity set the JAVA_HOME environment variable to point to a 64-bit JVM or JRE. You must also ensure that your PATH environment variable includes this 64-bit JAVA_HOME/bin directory, and that it appears before any other non-64-bit JVM/JRE. This step ensures that you are able to install all available components of tc Server (application server and AMS server/agent.)
Use the which java Unix command to ensure your PATH variable points to the 64-bit JVM/JRE:
prompt$ which java /usr/java64/jdk1.6.0_11/bin/java
6.
 
Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script. For example, on Unix:
prompt$ cd /home/springsource/tcServertmp prompt$ ./install.sh
The installer program performs some checks of your system then displays a menu of options. Depending on the components that are available in the distribution, as well as the components you want to install on your computer, pick one or both of the following procedures marked in bold:
Note that you must run the install.sh script from the directory in which it lives, and not from any other directory, or you will get an error.
7.
 
To install one or both of the AMS components, follow these steps:
a.
 
Enter the indicated number for the quick install that uses default values as much as possible; otherwise, enter the indicated number for a full install in which you provide values for all properties. If this is the first time you install tc Server, SpringSource recommends you choose the quick-install option.
The install program performs some checks of your system and then prints the AMS installation menu. See Installing HQ for details about the full install.
b.
 
Enter the indicated number to install only the AMS server (if available); otherwise, enter the indicated number to install only the AMS agent, or both numbers (separated by commas) to install both the AMS server and agent on this computer.
c.
 
Enter the full pathname of the directory in which you want to install the AMS component(s).
> Important: The specified directory must already exist; the install program does not create it for you.
The install program creates a directory under this main AMS installation directory for each corresponding component: for example, agent-2.0.0 and/or server-2.0.0.
If you are installing both components at once, the installer program asks you for the installation directory for each component, which means you can install them in separate locations.
d.
 
If you're installing AMS server, enter the fully qualified domain name of the SMTP server that AMS will use to send email messages; the default value is the domain name of the computer on which you are running the install program.
e.
 
(Unix only) If you are installing AMS server, the install script asks you to login to a different terminal window as the root user and run a script called tune-os.sh to set the proper shared memory settings to run the built-in database. This is a SpringSource AMS requirement. Do not close the first terminal window from which you ran the initial installer script while you perform this step. When complete, go back to the installer terminal window and press Enter to continue with the installation.
The following information is provided for administrators who might need to know exactly what the tune-os.sh script does, especially because it must be run as the root user. The script:
 
Checks to see if the file /etc/sysctl.conf exists. If it does not exist, the script creates it and includes the following line: kernel.shmmax=2147483648.
 
If the /etc/sysctl.conf file does exist, the script checks that the kernel.shmmax value is specified in the file. If it is not specified, the script appends the value to sysctl.conf and adds it to /proc/sys/kernel/shmmax
 
If the kernel.shmmax value is already specified, the script checks to see if the shmmax value is large enough (at least 2147483648). If it is large enough, the script skips it. If the value is too small, the script backups the current sysctl.conf file, creates a new file with the kernel.shmmax size set to 2147483648, and then updates the /proc/sys/kernel/shmmax file with that value.
f.
 
When the installation of the AMS components is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)
8.
 
To install tc Server application server, follow these steps:
a.
 
Enter the indicated number to install the tc Server application server.
b.
 
Enter the full pathname of the directory into which you want to install the tc Server application server.
> Important: The specified directory must already exist; the install program does not create it for you.
c.
 
After confirming your entry, the install program installs tc Server and then returns you to the main installer menu.
9.
 
Enter the indicated number to exit when you have finished installing all the required components for this computer.
Silently Installing a Managed Node or Application Server
If you are installing either a managed node (AMS agent and application server) or just the application server, you can pass properties to the install.sh or install.bat script rather than run the script interactively; this is referred to as silent installation. This feature is not available when installing the full distribution (AMS server, AMS agent, and application server.)
To install silently:
1.
 
Download and unzip the distribution, as described in the first four steps of the typical installation procedure.
2.
 
Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script, passing it the following two properties:
 
-t appserverdir: Specifies the full pathname of the directory where you want to install the tc Server application server component.
 
-a agentdir: Specifies the full pathname of the directory where you want to install the AMS agent.
For example, to install the application server in the /home/tcserverApp directory and the AMS agent in the /home/tcserverAgent directory, run the following command:
prompt$ ./install.sh -t /home/tcserverApp -a /home/tcserverAgent
Installing Tomcat Server Using the Self-Extracting JAR File
The self-extracting JAR file that contains only the base Tomcat server is called tcServer-version-tomcat.sfx.jar. This JAR file does not contain an installation script; rather, you must perform the installation yourself using the following procedure:
1.
 
Open a terminal (Unix) or command (Window) window and change to the directory into which you want to install Tomcat server.
2.
 
Unjar the self-extracting file by running the java -jar path-to-file/tcServer-version-tomcat.sfx.jar command, where path-to-file refers to the location of the JAR file and version refers to the version of tc Server, such as 6.0.20.C-GA. For example:
prompt$ java -jar /home/downloads/tcServer-6.0.20.C-GA-tomcat.sfx.jar
The JAR file extracts its contents into a new tcServer-6.0 sub-directory.
3.
 
(Unix only) Change to the tcServer-6.0 directory and change the permissions of all *.sh files to make them executable. For example, the following Unix find command searches for all files with the sh extension and sets their permissions:
prompt$ find . -type f -name '*.sh' -exec chmod +x "{}" \;
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 starting the various components of tc Server and getting started with the AMS console.
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. The section includes the following topics:
When you install the tc Server application server itself (as opposed to the AMS-related components), the install script asks you for a main installation directory; the install script then creates a sub-directory under the inputted directory called tcServer-6.0 that contains all tc Server-related files.
The tcServer-6.0 directory in turn contains the following directories and files:
 
tomcat-version, where version is the version of tc Server, such as tomcat-6.0.20.C : 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.
Users who want to use the standard Apache Tomcat server layout should use this directory as usual.
 
tijars : This directory contains JAR files used by tc Server that are different to standard Apache Tomcat.
 
tcserver-instance.sh|bat : Scripts for creating new tc Server instances when using the SpringSource directory layout, rather than the standard Apache layout. See Differences between the SpringSource and ASF Layouts of tc Server for information about these two directory layouts.
When you create a new server instance using this script, the script creates a sub-directory of the tcServer-6.0 directory with the same name as the new server instance; this new directory is the CATALINA_BASE of the server instance. The new directory contains the server-specific configuration files, its own Web application deployment directory, log files, and so on.
 
tcserver-ctl.sh|bat : Main tc Server control scripts. The bin directories of individual tc Server 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 also specify the name of the tc Server instance.
As already implied, after installing tc Server, you can chose to use the following two directory layouts for your tc Server instance(s):
 
SpringSource layout
 
Standard Apache (ASF) layout
The SpringSource layout differs slightly from the Apache layout in that SpringSource separates the runtime binaries from the configuration data. For additional details about how the SpringSource layout differs from standard Apache, see Differences between the SpringSource and ASF Layouts of tc Server. Unless otherwise indicated, it is assumed that you are using the SpringSource directory layout.
tc Server Variables
The following two tc Server variables are used extensively in the documentation.
 
CATALINA_HOME: Represents the root directory of your tc Server installation. For both layouts (SpringSource and ASF), the CATALINA_HOME variable points to the same directory: INSTALL_DIR/tcServer-6.0/tomcat-version, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver, and version is the version of tc Server, such as 6.0.20.C.
The CATALINA_HOME directory always contains, for example, a bin sub-directory that in turn contains the tc Server binary files.
 
CATALINA_BASE: Represents the root directory of a particular tc Server instance. The CATALINA_BASE directory always contains, for example, the conf sub-directory that in turn contains the configuration files for the particular tc Server instance.
In the ASF layout, CATALINA_BASE is the same as CATALINA_HOME, namely INSTALL_DIR/tcServer-6.0/tomcat-version. In the SpringSource layout, however, CATALINA_BASE is different and points to the directory created by the tcserver-instance.sh script.
tc Server Directory Structure
After you install tc Server, the CATALINA_HOME and CATALINA_BASE directories contain the following sub-directories. As a reminder, when using the ASF directory layout, CATALINA_HOME and CATALINA_BASE are the same.
 
CATALINA_HOME/bin: ASF layout only. Startup, shutdown, and other scripts, as well as tc Server binary files. The *.sh files (for Unix systems) are functional duplicates of the *.bat files (for Windows systems).
 
CATALINA_BASE/bin: SpringSource layout only. Contains the tcserver-ctl.* scripts to start and stop tc Server, as well as the setenv.* scripts.
 
CATALINA_BASE/conf: Contains the configuration files for the tc Server instance, such as server.xml, web.xml, context.xml, and so on.
 
CATALINA_BASE/lib: Contains resources shared by all Web applications deployed to the tc Server instance.
 
CATALINA_BASE/logs: Location of the logs files.
 
CATALINA_BASE/webapps: Deployment directory for the Web applications deployed to the tc Server instance.
 
CATALINA_BASE/work: Temporary work directory for all deployed Web applications.
 
CATALINA_BASE/temp: Directory used by the JVM for temporary files.
tc Server Configuration Files
You configure a particular tc Server instance by changing its configuration files (either by editing the XML file by hand or using AMS); later chapters of the documentation describe how to do this. All the configuration files for a tc Server are located in its CATALINA_BASE/conf directory. The most important configuration files are as follows:
 
server.xml: Main configuration file for a tc Server instance. It configures the behavior of the servlet/JSP container. By default, the server.xml file for a tc Server instance uses variable substitution for configuration properties that must be unique across multiple server instances computer, such as HTTP and JMX port numbers. These variables take the form ${var}. For example, the variable for the HTTP port that tc Server listens to is ${http.port}. The specific values for these variables for a particular server instance are stored in the conf/catalina.properties file, in the same directory as the server.xml file.
 
catalina.properties: Properties file that contains the server 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 Server 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 Server instance as a Windows service. The Wrapper correctly handles user log outs under Windows, service dependencies, and the ability to run services which interact with the desktop.
Differences between the SpringSource and ASF Layouts of tc Server
SpringSource tc Server provides two "flavors" of the tc Server application server itself, 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/tcServer-6.0/tomcat-version, where version is the version of tc Server such as 6.0.20.C. This directory is ready to use immediately, which means it includes a tc Server instance by default.
The SpringSource layout is slightly different, mostly in that it supports multiple instances of tc Server 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 Server 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 a script for easily creating new instances of tc Server. The SpringSource layout does not provide a default server instance right after installation; you must create one using the script. For details, see Creating Instances in the SpringSource Layout.
Post-Installation Tasks
After you have installed the components of tc Server (tc Server application server, AMS Server, and the AMS agents) on all relevant computers, post-installation tasks include starting the AMS server and agents, starting tc Server instances, deploying Web application to tc Server, and invoking and using AMS to monitor and configure tc Server.
The appropriate next step, however, depends on the layout (ASF or SpringSource) of tc Server you want to use. In particular:
 
If you want to use the ASF layout for your tc Server instances, then an instance of the server already exists by default and you can immediately start it, deploy applications, and manage it with AMS; see Starting and Stopping tc Server Instances.
 
If you want to use the SpringSource layout for your tc Server instances, you must first create a tc Server instance, because one is not installed for you by default. For details, see Creating a New tc Server Instance.
See Overview of tc Server Directories, Variables, and Configuration Files for details about the differences in the two layouts: ASF and SpringSource.
Creating a New tc Server Instance
The following sections describe how to create new instances of tc server for each of the two types of layouts: SpringSource and ASF:
See Differences between the SpringSource and ASF Layouts of tc Server for details about the differences between these two layouts.
If you want to use the SpringSource layout of tc Server, then you are required to create a new instance because the out-of-the-box installation of tc Server does not automatically provide one for you. If, however, you want to use the ASF (or standard Apache) directory layout, then an instance already exists as soon as you install tc Server. Therefore, the ASF section below describes how to create a new instance in additional to the default out-of-the-box one.
NOTE: Each topic covers both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platorm, change these to back slashes (\).
Creating Instances in the SpringSource Layout
This section describes how to create a new tc Server instance when using the SpringSource layout.
1.
 
Open a terminal window (Unix) or command prompt (Windows).
2.
 
Change to the INSTALL_DIR/tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver. This directory also contains the script for creating a new instance, tcserver-instance.sh (Unix) and tcserver-instance.bat (Windows). For example:
prompt$ cd /home/tcServer/tcServer-6.0
3.
 
Run the tcserver-instance.sh (Unix) or tcserver-instance.bat (Windows) script, passing it the following required parameters at a minimum:
 
-s serverName : Replace serverName with the name of your new tc Server instance. See Best Practice: Naming tc Server Instances for tips on naming an instance.
 
-j path_to_jdk : Replace path_to_jdk with the full pathname of your installed JDK. NOTE: This parameter is not required if you have set the JAVA_HOME variable in your environment to point to the JDK.
For example, on Unix:
prompt$./tcserver-instance.sh -s myserver -j /home/java/jdk1.6.0_12
When the script completes, the new server instance is located by default in the INSTALL_DIR/tcServer-6.0/myserver directory. This directory is also the value of the CATALINA_BASE variable for this server instance. The tc Server instance uses the JDK located in the /home/java/jdk1.6.0_12 directory. Additionally, the ports of the server instance are the default values, as follows:
 
HTTP listen port: 8080
 
JMX port: 6969
 
AJP port: 8009
 
Shutdown port: -1
The version of the tc Server instance is the highest version that the script finds in the installation directory, for example 6.0.20.C.
You can specify additional optional parameters of the tcserver-instance.sh script, as described in tcserver-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 server 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.
tcserver-instance.sh Reference
The following table lists all the available options of the tcserver-instance.sh|bat command.
There are two ways to specify each option; both are completely equivalent. The way you chose is completely up to you based on your preference. You can specify an option with a single dash and a letter (such as -s) or two dashes and a word (such as --server). The following table shows both ways of specifying the options.
Option (Single Dash)
Option (Double Dash)
Description
Required?
-s serverName
--server serverName
Replace serverName with the name of your new tc Server instance. See Best Practice: Naming tc Server Instances for tips on naming an instance.
Yes.
-v version
--tomcatver version
Replace version with the version of the new tc Server instance, such as 6.0.20.C.
The valid values of this option depend on the versions of tc Server that you have installed. The tcserver-instance.sh script determines the list of available versions by searching for tomcat-XXX directories, where XXX follows a pattern such as 6.0.20.C. Use the -h option of the tcserver-instance.sh script to see the list of known tc Server versions; the list is outputted in the information about the -v option.
If you do not specify this option, the tcserver-instance script picks the highest version of tc Server it can find in the installation directory. For example, if 6.0.19.A, 6.0.20.A and 6.0.20.C are all present, and you don't specify this option, then the script automatically picks 6.0.20.C.
No.
-j path_to_jdk
--javahome path_to_jdk
Replace path_to_jdk with the full pathname of your installed JDK. The default value of this option is the value of the JAVA_HOME environment variable.
The tcserver-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 to just a JRE. For most use cases, setting the JAVA_HOME variable by using this option is adequate and you do not need to set JRE_HOME with the -r option as well.
Only required if you have not set the JAVA_HOME variable in your environment to point to the JDK.
-r path_to_jre
--jrehome path_to_jre
Replace path_to_jre with the full pathname of your installed Java runtime environment (JRE). The default value of this option is the value of the JRE_HOME environment variable.
The tcserver-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 to just 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.
-d tcServerDir
--tcserverdir tcServerDir
Replace tcServerDir with the full pathname of the tc Server installation. Use this parameter if you are running the tcserver-instance.sh script from a location other than its default home directory. The default value of this parameter is the current working directory.
Only required if you are not running the tcserver-instance.sh from its default location: INSTALL_DIR/tcServer-6.0.
-n instanceDir
--instancedir instanceDir
Replace instanceDir with the full or relative pathname of the directory in which you want the new tc Server instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcserver-instance.sh|bat script.
If you do not specify this option, the tcserver-instance.sh|bat script creates the new instances in the INSTALL_DIR/tcServer-6.0 directory.
No.
-t template_location
--template template_location
Use this option to apply a template to a newly-created tc Server instance.
In this context, a tc Server template refers to a set of customized tc Server files that the tcserver-instance script copies to the instance it just created. The template files are organized in the standard Tomcat hierarchy; for example, configuration files are in the conf directory and binary files are in the bin directory. When the tcserver-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:
 
The name of an existing sub-directory of the INSTALL_DIR/tcServer-6.0/templates directory.
 
An absolute path to a directory that contains a tc Server template, such as /home/templates/tcServer/mytemplate.
 
A file that contains a list of absolute template directories. If you specify a file, the tcserver-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 Server Instance Using a Template and Creating tc Server Templates.
No.
-f
--force
Forces the script to create a new server instance, even if one already exists. By default the script does not force the creation.
If you specify this parameter against an existing server instance, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. This is because 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 want to leave the user-specific files, such as Web applications, alone.
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 above.
Warning: Be sure that all tc Server instances on the same computer have unique port numbers.
No.
-p
--ports
Specifies the 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 above.
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 you specifed the following value for this option:
--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 Server instances on the same computer have unique port numbers.
No.
-c
--create
Specifies that you want the tcserver-instance.sh script to create a new tc Server instance.
This is the default mode of the script.
No.
-m
--modifyver
Use this option to modify the version of tc Server that an existing tc Server instance uses.
You use this option together with the -s serverName option to specify the tc Server instance you want to modify and with the -v version option to specify the new version of the instance. If you do not explicitly specify -v version on the command line, the tcserver-instance script uses the default value of -v, which is the highest version it can find.
Note: You can use this option only against an existing tc Server instance; you cannot use this option when creating a new instance. It is assumed that you have already installed the tc Server version to which you want to modify the existing instance.
No.
-a arch
--architecture
Windows only. Specifies whether you want the tcserver-instance.bat script to create a 32-bit or 64-bit version of the Windows service wrapper.
Valid values are win32 and winx86_64. The default value is win32.
If you specify winx86_64 for this option, the Windows computer on which tc Server is installed must use a 64-bit operating system; note that tc Server supports only x86 64-bit architecture, not the Itanium 64-bit. Additionally, you must specify that the tc Server instance use a 64-bit JVM (with either the -j or -r option of the tcserver-instance.bat command). Similarly, if you specify win32 (default value), then you must specify a 32-bit JVM.
No.
-l
--list
Lists all the server 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.
-h
--help
Outputs information about all the available options of tcserver-instance.sh|bat.
No.
For example, to request that you be prompted for port numbers and that the tc Server installation directory is /home/tcserver/tcServer6.0, run the following:
prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -j /home/java/jdk1.6.0_12 -d /home/tcserver/tcServer6.0 -i
The following example shows how to modify an existing tc Server instance called myotherserver to use version 6.0.20.C:
prompt$./tcserver-instance.sh -s myotherserver -m -v 6.0.20.C
Best Practice: Naming tc Server Instances
The name of a tc Server 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 Server instance in the /home/tcserver/tcServer-6.0/myServer directory, then its name is myServer.
The AMS Console also uses this naming convention when first identifying a tc Server instance. In particular, AMS displays an instance with the name platform-resource tc Server catalina-base-dir, where platform-resource refers to the computer on which tc Server is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Server instance without the leading directory pathnames. The AMS console 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 AMS console with the same names. This makes it difficult to differentiate multiple tc Server 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 AMS:
 
/home/tcserver1/tcServer-6.0/myServer
 
/home/tcserver2/tcServer-6.0/myServer
Although they are completely different instances, they will both show up in AMS with the name my-desktop tc Server myServer.
For this reason, SpringSource recommends as a best practice that you use unique names for the main installation directory for each tc Server instance on the same computer. For example, the following two instances will show up in the AMS console with different names:
 
/home/tcserver1/tcServer-6.0/myServer
 
/home/tcserver2/tcServer-6.0/myOtherServer
Creating a tc Server Instance Using a Template
When you create a new tc Server instance using the tcserver-instance script, you can use the -t (or --template) option to specify a tc Server template. A template is simply a directory that contains additional or customized tc Server instance files, such as server.xml or JAR files. When you specify the -t option, the tcserver-instance script first creates the tc Server instance as usual, which mostly entails copying over the standard Tomcat files from the tcServer6.0/tomcat-version directory to the new instance directory, where version refers to the version of tc Server, such as 6.0.20.C. Then, after the script has created a standard tc Server instance, the script then copies over the files and sub-directories contained in the specified tc Server template.
To use this feature, a template must already exist. You can create your own template, as described in Creating tc Server Templates.
Templates are all contained in a single directory and are organized in the standard Tomcat sub-directory hierarchy. For example, configuration files live in the conf directory and JAR files live in the lib directory. If you are creating your own template, then you can also create additional sub-directories if you choose. When the tcserver-instance script applies the template after it has created a new tc Server instance, it copies over all the files, including those in sub-directories. Depending on the contents of the template directory, the new tc Server 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 either a template directory or a file that lists multiple template directories. If the template argument is just a single name, then the tcserver-instance script assumes the template directory is located in the INSTALL_DIR/tcServer-6.0/template directory. You can also use an absolute directory name to specify a template directory in another location.
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 tcserver-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 Server instance called myserver using a template called my-super-template that is assumed to live in the templates directory:
prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -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$./tcserver-instance.sh -s myserver -v 6.0.20.C -t /home/templates/tcServer/mytemplate
The following example shows how to create an instance using multiple templates by specifying a file that lists the template directories using absolute pathnames:
prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -t templates.txt
The templates.txt file would in turn contain a list of absolute template directory names:
/home/templates/tcServer/mytemplate /home/templates/tcServer/myothertemplate
Creating tc Server Templates
To use the templating feature, you create your own templates with your own customizations which you can then use later to create new customized tc Server instances.
The template must be located in a single directory, and the name of the template is the name of the directory. SpringSource recommends that you create the templates in the INSTALL_DIR/tcServer-6.0/templates directory so you can keep all your templates together, although it is not required. Then, for each Tomcat file you want to customize, create the sub-directory in which it lives and then create the customized file in that subdirectory. For example, if you want to create a customized server.xml, create the file in the conf sub-directory. If you want to add a new shell script, add it to the bin directory. You can also create your own sub-directories that will be copied to the new instance. Finally, you can add application JAR files to the webapps directory if you want these applications to be automatically deployed each time the new instance is started.
The following file listing shows an example of a template called my-super-template; use it as a guide when creating your own templates. Note that the template customizes the standard conf/context.xml file and adds JAR files to the lib and webapps directory and creates a new sub-directory (webapps-lib, alongside webapps), amongst 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/myapp.yml my-super-template/instrument-tomcat.xml
Creating Instances in the ASF Layout
The following procedure describes how to create a new tc Server instance when using the ASF layout.
1.
 
Open a terminal window (Unix) or command prompt (Windows).
2.
 
Run the main tc Server install program install.sh and install a new tc Server application server (option 3) into a new directory, different from the directory in which you installed the original tc Server application server. See Installing tc Server: Typical Steps.
3.
 
If you are going to run this tc Server instance on the same computer as another tc Server instance, you must ensure that the various port numbers are unique. You configure these ports in the INSTALL_DIR/tcserver-6.0/tomcat-version/conf/server.xml file, where INSTALL_DIR refers to the directory in which you just installed tc Server and version refers to the version of tc Server, such as 6.0.20.C. 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 Server 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 AMS uses to communicate with the tc Server instance so that you can manage it.
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.
Starting and Stopping tc Server Instances
This section describes how to start and stop tc Server instances on both Windows and Unix platforms. The following sections describe using the tcserver-ctl.sh|bat command script to start and stop the instances interactively, as well as how to configure your computer so the instances start and stop automatically without you having to specifically run the command script:
After you installed the tc Server application server, you had the option of using the SpringSource layout or the standard Apache (ASF) layout. These two types of tc Server are essentially the same, but differ slightly in their directory structure; see Differences between the SpringSource and ASF Layouts of tc Server for more information. For this reason, the Unix or Windows sections are further sub-divided into sections for each type of layout.
Unix: Starting and Stopping Instances Interactively Using tcserver-ctl.sh
To take full advantage of the tc Server features, such as deadlock detection, you must start tc Server using version 1.6 of the JDK.
If you are using the SpringSource layout and specified the --javahome path_to_jdk_1.6 option when creating a new instance using the tcserver-instance.sh script, then you are all set. If, however, you are using the ASF layout, or you didn't specify the --javahome option for the SpringSource layout, then you can manually update the file called setenv.sh in the CATALINA_BASE/bin directory and add a line to the file that specifies the value of the JAVA_HOME variable. For example:
export JAVA_HOME=/home/java/jdk1.6.0_12
You can set other environment variables in this file too, such as JAVA_OPTS and CATALINA_OPTS to specify properties for the JVM on which tc Server runs. See the file CATALINA_HOME/bin/setenv.sh for an example.
To download and install Sun Microsystem's JDK 1.6, see Java SE Downloads.
SpringSource Layout
If you are using the SpringSource layout of tc Server, you must first create a tc Server instance using the tcserver-instance.sh command script, as described in Creating a New tc Server Instance. The default installation of tc Server of the SpringSource layout does not include a server instance.
By default, this script creates all tc Server instances under the INSTALL_DIR/tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver. Each particular server instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is, of course, the default behavior of the command script; you might, however, have specified a different location of your tc Server instance.
In the SpringSource layout, CATALINA_HOME is INSTALL_DIR/tcServer-6.0/tomcat-version, where version refers to the version of tc Server, such as /home/tcserver/tcServer-6.0/tomcat-6.0.20.C.
To start and stop tc Server instances that use the SpringSource directory structure layout, follow these steps:
1.
 
Start a terminal window and change to the CATALINA_BASE/bin directory of the tc Server you want to start or stop.
For example, if you installed tc Server in /home/tcserver and created a new tc Server instance called myserver:
prompt$ cd /home/tcserver/tcServer-6.0/myserver/bin
2.
 
Start tc Server instance by executing the tcserver-ctl.sh start command. For example:
prompt$ ./tcserver-ctl.sh start
This command starts the tc Server as a daemon under the current user account.
3.
 
Stop a currently running tc Server instance by executing the tcserver-ctl.sh stop command:
prompt$ ./tcserver-ctl.sh stop
See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.
ASF Layout
To stop and start tc Server instances in the ASF layout, follow these steps:
1.
 
Start a terminal window and change to the CATALINA_HOME/bin directory of the tc Server you want to start or stop.
For example, if you installed tc Server in /home/tcserver and are using version 6.0.20.C of tc Server:
prompt$ cd /home/tcserver/tcServer-6.0/tomcat-6.0.20.C/bin
2.
 
Start tc Server by executing the tcserver-ctl.sh start command. For example:
prompt$ ./tcserver-ctl.sh start
This command starts the tc Server as a daemon under the current user account.
3.
 
Stop a currently running tc Server by executing the tcserver-ctl.sh stop. For example:
prompt$ ./tcserver-ctl.sh stop
See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.
NOTE: The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.sh. This script is provided for users who are already familiar with Apache Tomcat and would prefer to continue using the same script to start and stop the server.
The two methods of starting the server (catalina.sh start and tcserver-ctl.sh start) are essentially the same. However, the two methods of stopping the server differ in the following important way: catalina.sh stop takes into account the value of the SHUTDOWN port and if it is -1, the script does not stop the server. The tcserver-ctl.sh stop command, however, stops the server even if its SHUTDOWN port is set to -1.
Unix: Automatically Starting Instances at System Boot Time
On Unix platforms, the tc Server installation includes a command script file called INSTALL_DIR/tcServer-6.0/boot.rc.template, which is a template file that you can use to customize your Unix boot process so that tc Server 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 Server instance environment. Consult your Unix administration documentation for further details about customizing the boot process.
There is a one-to-one relationship between a boot.rc file and a tc Server instance. This means, for example, that if you want to automatically start multiple tc Server instances on the same Unix computer, you must create separate boot.rc files for each server instance, modify each of them to reflect the environment of the corresponding tc Server 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: The Unix user account that you want the tc Server instance to run as.
 
TC_SERVER_HOME: The absolute pathname to the tc Server installation home directory. This directory will be something like /home/tcserver/tcServer-6.0, where /home/tcserver is the directory into which you installed tc Server.
 
INSTANCE_BASE: The absolute pathname to the directory that contains your tc Server 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 Server instances can be located anywhere, in which case you should specify the absolute pathname.
 
INSTANCE_NAME: The name of the tc Server 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: The absolute pathname of the home directory of the JDK you want the tc Server instance to use.
The following example shows how to specify that the tc Server home directory is /home/tcserver/tcServer-6.0, that the instance directory is the same as the tc Server home directory, that the instance name is myserver, that the JDK is located in /home/java/jdk1.6.0_11 and that you want the tomcat user to start the tc Server process:
TOMCAT_USER=tomcat TC_SERVER_HOME=/home/tcserver/tcServer-6.0 INSTANCE_BASE=$TC_SERVER_HOME INSTANCE_NAME=myserver JAVA_HOME=/home/java/jdk1.6.0_11
Be sure you do not modify any part of the boot.rc.template file after the text DO NOT EDIT BEYOND THIS LINE.
Windows: Starting and Stopping Instances As Windows Services
To take full advantage of the tc Server features, such as deadlock detection, you must start the tc Server instance using version 1.6 of the JDK.
If you are using the SpringSource layout and specified the --javahome path_to_jdk_1.6 option when creating a new instance using the tcserver-instance.bat script, then you are all set. If, however, you are using the ASF layout, or you didn't specify the --javahome option for the SpringSource layout, then you can manually update the file called setenv.bat in the CATALINA_BASE\bin directory and add a line to the file that specifies the value of the JAVA_HOME variable. For example:
set JAVA_HOME=c:\home\java\jdk1.6.0_12
You can set other environment variables in this file too, such as JAVA_OPTS and CATALINA_OPTS to specify properties for the JVM on which tc Server runs. See the file CATALINA_HOME\bin\setenv.bat for an example.
To download and install Sun Microsystem's JDK 1.6, see Java SE Downloads.
SpringSource Layout
If you are using the SpringSource layout of tc Server, you must first create a tc Server instance using the tcserver-instance.bat command script, as described in Creating a New tc Server Instance. The default installation of tc Server (SpringSource) does not include a server instance.
By default, this script creates all tc Server instances under the INSTALL_DIR\tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as c:\home\tcserver. Each particular server instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is, of course, the default behavior of the command script; you might, however, have specified a different location of your tc Server instance.
In the SpringSource layout, CATALINA_HOME is INSTALL_DIR\tcServer-6.0\tomcat-version, where version refers to the version of tc Server, such as c:\home\tcserver\tcServer-6.0\tomcat-6.0.20.C.
To start and stop tc Server instances that use the SpringSource directory structure layout, follow these steps:
1.
 
Start a commmand prompt and change to the CATALINA_BASE\bin directory of the tc Server you want to start or stop.
For example, if you installed tc Server in c:\home\tcserver and created a new tc Server instance called myserver:
prompt$ cd c:\home\tcserver\tcServer-6.0\myserver\bin
2.
 
Install tc Server as a Windows service by executing the following command:
prompt$ tcserver-ctl.bat install
Once installed as a Windows service you use the Windows Services console to stop and start the service. It is displayed in the Windows Services console with the name SpringSource tcServer - Server servername.
3.
 
To uninstall the tc Server service, execute the following command:
prompt$ tcserver-ctl.bat uninstall
Although SpringSource recommends that you always install tc Server as a Windows service and stop and start it using the Services console, you can also stop and start the server instance manually. See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.
ASF Layout
To stop and start tc Server instances in the ASF layout, follow these steps:
1.
 
Start a commmand prompt and change to the CATALINA_HOME\bin directory of the tc Server you want to start or stop.
For example, if you installed tc Server in c:\home\tcserver and are using version 6.0.20.C:
prompt$ cd c:\home\tcserver\tcServer-6.0\tomcat-6.0.20.C\bin
2.
 
Install tc Server as a Windows service by executing the following command:
prompt$ tcserver-ctl.bat install
Once 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 tcServer.
3.
 
To uninstall the tc Server service, execute the following command:
prompt$ tcserver-ctl.bat uninstall
Although SpringSource recommends that you always install tc Server as a Windows service and stop and start it using the Services console, you can also stop and start the server instance manually. See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.
NOTE: The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.bat. This script is provided for users who are already familiar with Apache Tomcat and would prefer to continue using the same script to start and stop the server.
The two methods of starting the server (catalina.bat start and tcserver-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 tcserver-ctl.bat stop command, however, stops the server even if its SHUTDOWN port is set to -1.
The Windows Java Service Wrapper
On Windows, tc Server uses a Java Service Wrapper from Tanuki Software to install the tc Server instance as a Windows service. The Wrapper correctly handles user log outs 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 server instance, such as c:\home\tcserver\tcServer-6.0\myserver. In most circumstances, there is no need for you to update this file because the default one created when you created the tc Server 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 Server instance on Windows using the tcserver-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 tcserver-ctl.bat script overrides this generic value with something else (such as winx86_64) if in fact you are running the tc Server instance on a 64-bit computer.
For details about the available configuration properties, see Configuration Property Overview.
tcserver-ctl Command Reference
You use the tcserver-ctl.sh (Unix) and tcserver-ctl.bat (Windows) command script to manage tc Server instances.
Typically, you run the command from the bin directory of the server instance itself. However, you can also run it from the INSTALL_DIR/tcServer-6.0 directory if you specify the name of the instance, where INSTALL_DIR refers to the directory in which you installed tc Server.
For example, to start a tc Server instance called myserver from the bin directory of the instance itself on Unix, run the following commands:
prompt$ cd /home/tcserver/tcServer-6.0/myserver/bin prompt$ ./tcserver-ctl.sh start
You can accomplish the same thing by running the command from the tcServer-6.0 directory by specifying the name of the instance:
prompt$ cd /home/tcserver/tcServer-6.0 prompt$ ./tcserver-ctl.sh myserver start
It is assumed in the remainder of this section, however, that you are running the command script from the bin directory of the tc Server instance.
The following table lists the commands and options of the tcserver-ctl script. The table also indicates whether the command is supported on Unix, Windows, or both.
Command
Description
Platform
install run-as-user
Installs the tc Server 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 Server 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. Note that you can specify only user accounts that have their Logon as Service right set to run a Windows service; for details on how to set this for a particular user, 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. Note that tc Server still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it will fail with a logon error. To fix the problem, you must then uninstall the service, then reinstall it with the correct password.
Windows only
uninstall
Uninstalls the tc Server instance from the Windows Service.
Windows only
start
Starts the tc Server instance as a daemon process.
On Windows, you must have previously installed the tc Server instance as a Windows service to be able to start it using the tcserver-ctl.bat start command; see the documentation on the tcserver-ctl.bat install command in this table for more information.
Unix and Windows
restart
Stops, and then immediately starts, a running tc Server instance. As with the start command, restart starts the instance as a daemon process.
On Windows, you must have previously installed the tc Server instance as a Windows service to be able to restart it using the tcserver-ctl.bat restart command; see the documentation on the tcserver-ctl.bat install command in this table for more information.
Unix and Windows
run
Starts the tc Server instance as a foreground process.
Unix and Windows
batch
Runs the tc Server instance using the catalina.bat script as a batch job. Specifically, the script starts the tc Server instance by running the following command: %CATALINA_HOME%\bin\catalina.bat run.
Windows only
stop timeout
Stops a running tc Server instance. By default, the tcserver-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.
You can set your own timeout value by specifying an integer option for the number of seconds; for example:
prompt$ ./tcserver-ctl.sh stop 10
Unix and Windows
status
Reports the status of a tc Server instance, such as whether it is running or stopped, as well as useful information such as the directory from which the tc Server instance gets its binary files, the main instance source directory, and so on.
Unix and Windows
Setting the Logon As Service Right for a Windows User
This section applies to Windows platforms only.
The tcserver-ctl.bat install command has an optional run-as-user parameter with which you can specify the user account that you want the tc Server service to actually run as when you start the service using 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, follow these steps:
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.
Note that 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 Server service as a specific account under those versions of Windows.
Starting and Stopping the AMS Server and Agents
On Unix platforms, you always use shell scripts to start and stop the AMS server and agent. On Windows, it is recommended that you install both the server and agents as Windows Services, which means you use the Windows Services console to subsequently stop and start them, as well as specify whether they should start automatically when the operating system starts. The section below describes how to install the server and agents as Windows services.
Depending on how you have configured tc Server, you might run the commands to start/stop the AMS agent and server on the same computer or on different computers.
NOTE: If you are running the AMS agent or server on a computer that uses a 64-bit operating system, you must set the HQ_JAVA_HOME environment variable to point to the full pathname of the 64-bit JDK or JRE installed on your computer. This is because the AMS components will not work correctly with the default JDK/JRE when running on 64-bit operating systems. See Supported Configurations for the list of supported 64-bit operating systems.
Unix
To start and stop the AMS Server:
1.
 
Start a new terminal window.
2.
 
Change to the AMS_SERVER_INSTALL_DIR/bin directory, where AMS_SERVER_INSTALL_DIR refers to the directory in which you installed the AMS server, such as /home/tcserver/server-2.0.0:
prompt$ cd /home/tcserver/server-2.0.0/bin
3.
 
To start the AMS server, execute the following command:
prompt$ ./ams-server.sh start
The script displays startup information to stdout, then it detaches and runs in the background.
4.
 
To stop the AMS server, execute the following command:
prompt$ ./ams-server.sh stop
The server is fully stopped when you see the message AMS Server is stopped.
See the AMS_SERVER_INSTALL_DIR/logs/server.log for details about the starting or stopping of the AMS server.
To start and stop the AMS agent:
1.
 
Start a new terminal window.
2.
 
Check the Supported Configurations: AMS Agent table to verify whether your particular platform requires you to set the HQ_JAVA_HOME in your environment before you start the AMS agent. Only certain platforms require this step. If your platform is one of them, you must set this environment variable to point to the location of an previously installed JRE/JVM 1.5.
3.
 
Change to the AMS_AGENT_INSTALL_DIR directory, where AMS_AGENT_INSTALL_DIR refers to the directory in which you installed the AMS agent, such as /home/tcserver/agent-2.0.0:
prompt$ cd /home/tcserver/agent-2.0.0
4.
 
To start the AMS agent, execute the following command:
prompt$ ./ams-agent.sh start
The script displays Agent successfully started on success.
Attention: The first time you start the agent, the script requests information about the AMS server to which it will communicate; this is a one-time event and subsequent starts of the agent do not require this input. See Starting the AMS Agent For the First Time for details about the requested information.
5.
 
To stop the AMS agent, execute the following command:
prompt$ ./ams-agent.sh stop
The agent is fully stopped when you see the message Success -- agent is stopped!
See the AMS_AGENT_INSTALL_DIR/log/agent.log for details about the starting or stopping of the AMS agent.
Windows
To start and stop the AMS Server:
1.
 
Start a command prompt window.
2.
 
Change to the AMS_SERVER_INSTALL_DIR\bin directory, where AMS_SERVER_INSTALL_DIR refers to the directory in which you installed the AMS server, such as c:\tcserver\ams\server-2.0.0:
prompt> cd c:\tcserver\ams\server-2.0.0\bin
3.
 
The first time you start the AMS server, install it as a Windows service by executing the following command:
prompt> ams-ctl.bat install
You will see a Done. message when it finishes.
4.
 
Subsequently, start (and stop) the AMS Server using the Windows Service control panel. The AMS server is listed as SpringSource AMS Server.
5.
 
To uninstall the Windows service, execute the following command:
prompt> ams-ctl.bat uninstall
See the AMS_SERVER_INSTALL_DIR\logs\server.log for details about the starting or stopping of the AMS server.
NOTE: Although SpringSource recommends that, on Windows, you always install the AMS Server as a service and consequently start and stop it using the Windows Service control panel, you can also start and stop it manually if you so choose. To start the server, exectue the following command from the bin directory:
prompt> ams-ctl.bat start
The command starts a new command window with status messages about the start of the server.
To stop the server:
prompt> ams-ctl.bat stop
To start and stop the AMS agent:
1.
 
Start a command prompt window.
2.
 
Change to the AMS_AGENT_INSTALL_DIR directory, where AMS_AGENT_INSTALL_DIR refers to the directory in which you installed the AMS agent, such as c:\tcserver\ams\agent-2.0.0:
prompt> cd c:\tcserver\ams\agent-2.0.0
3.
 
The first time you start the AMS agent, you are required to run it from the command line by executing the following command:
prompt> ams-ctl.bat start
The command requests information about the AMS server to which it will communicate; this is a one-time event and subsequent starts of the agent do not require this input. See Starting the AMS Agent For the First Time for details about the requested information.
4.
 
After the first start process (described in the preceding step) has completed, install the AMS agent as a Windows service:
prompt> ams-ctl.bat install
You will see a Done. message when it finishes.
5.
 
Subsequently, start (and stop) the AMS agent using the Windows Service control panel. The AMS agent is listed as the SpringSource AMS Agent.
6.
 
To uninstall the Windows service, execute the following command:
prompt> ams-ctl.bat uninstall
See the AMS_AGENT_INSTALL_DIR\log\agent.log for details about the starting or stopping of the AMS agent.
NOTE: Although SpringSource recommends that, on Windows, you always install the AMS Agent as a service and consequently start and stop it using the Windows Service control panel, you can also start and stop it manually if you so choose. To start the agent, exectue the following command from the AMS_AGENT_INSTALL_DIR directory:
prompt> ams-ctl.bat start
The command starts a new command window with status messages about the start of the agent.
To stop the agent, run the following command:
prompt> ams-ctl.bat stop
Starting the AMS Agent For the First Time
The first time the AMS agent starts, it asks for information about the AMS server to which it will communicate. The following table describes the requested information.
Configuration Property
Description
Default
AMS Server IP Address
The IP address or fully qualified domain name of the running AMS Server. If the agent is on the same host as the server, the answer can be 127.0.0.1 to communicate on the loopback interface.
none
AMS Server <> AMS Agent secure communication
Specifies whether the AMS agent communicates with the AMS Server over HTTPS. If secure communication is not necessary (for instance, if the agent and server are on a private network), saying 'no' here increases the performance of agent/server communication.
no
AMS Server Port
The port the AMS agent uses to communicate with the AMS Server. If the answer to the question about communicating securely was 'yes', you must supply the HTTPS port; otherwise you must supply the HTTP port.
7080 (nonsecure) or 7443 (secure)
AMS Login
The username of an AMS user with sufficient permissions to create resources in AMS, such as the AMS administrator.
hqadmin
AMS Password
The password of the AMS user specified in the previous question.
none
AMS Agent IP Address
The IP address the AMS Server uses to contact this agent. If the agent is on the same host as the server, the answer can be 127.0.0.1 to communicate on the loopback interface. If there is a firewall between the AMS Server and agent, this would be the IP address of the firewall; the firewall must be configured to forward traffic intended for the AMS agent to the correct location.
Detected IP Address
AMS Agent Port
Similar to the previous question, this is the port with which the AMS Server communicates with the agent. Note that changing this value does not change the port the agent binds to on the current computer. The port the agent binds to is set in the agent.properties properties file. The property to set is agent.listenPort. There is no agent.listenPort specified by default, so the agent listens on 2144 by default. If the agent.listenPort is changed, this question must be answered accordingly. Additionally, if there is a firewall between the AMS agent and the AMS Server, this value should be the port the firewall is forwarding to the AMS agent.
2144
Getting Started with the AMS Console
After you have installed and started the AMS server and all the agents on all computers that host tc Server instances (and other resources such as Apache Tomcat), you invoke the AMS console in your browser so you can start monitoring and configuring the resources.
The following procedure describes how to access the AMS console, as well as additional steps to add tc Server to the AMS inventory and how to update the tc Servers' JMX configuration properties so that AMS can correctly manage them.
1.
 
Invoke the AMS Console in your browser using the following URL:
http://host:port
where:
 
host refers to the computer on which you installed the AMS server. If your browser is running on the same computer as the AMS server, you can use localhost or 127.0.0.1.
 
port refers to the TCP/IP listen port of the AMS Server, specified when you installed the server. The default value is 7080.
Tip: The TCP/IP listen port is configured in the AMS_SERVER/conf/hq-server.conf file, where AMS_SERVER is the directory in which you installed the AMS server. If the default listen port does not work, search this file for the actual value of the server.webapp.port property.
2.
 
At the loging screen, enter the administrator login. The default username and password is hqadmin.
Tip: The server administrator username and password are configured in the AMS_SERVER/data/hq-server-install.conf file, where AMS_SERVER is the directory in which you installed the AMS 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 AMS console, not its functionality. SpringSource recommends you select hqadmin then OK. You can change the default dashboard after you have logged in.
4.
 
The following graphic displays the main AMS dashboard, with some of the navigational objects highlighted, either because they are ones that you will always use or will use when you first 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 AMS, 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 AMS has auto-discovered but you have not yet dealt with (either adding them to the AMS inventory or skipping them). For example, if you started a tc Server instance before logging into AMS, then it should automatically show up in the auto-discovery portlet. In the next step you will add these resources to AMS' inventory.
 
Finally, the Help button provides context-sensitive online help, with useful information about what tasks you can perform on each AMS console page.
5.
 
Import your operating system platform, as well as tc Server and other resources running on the platform, into the AMS 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 Server application server shows up as platform-resource tc Server single-catalina-base-dir in the AMS console, where platform-resource refers to the computer on which tc Server is running and single-catalina-base-dir refers to the CATALINA_BASE directory of the tc Server instance without the leading directory pathnames (for example, myserver). Resources associated with the AMS components will also show up in the auto-discovery portlet, such as AMS Agent 2.0.0 and the Apache Tomcat server used by AMS AMS Tomcat 5.5.
Because of the auto-discovery feature of AMS, your operating system platform should automatically show up in the Auto-Discovery portlet on the main Dashboard screen of the AMS console. Other resources running on the operating system, such as tc Server, Apache Tomcat, and so on will also show up in the portlet. This is true for all computers running AMS agents that communicate with this AMS Server.
Tip: It can sometimes take a few minutes for a newly-started resource, such as tc Server, to show up in the auto-discovery portlet.
After clicking Add to Inventory, the selected resources show up in the Recently Added portlet of the main Dashboard.
6.
 
Click the Resources > Browse link at the top of the AMS console.
 
This brings you to a console page from which you can view all the resources in the AMS inventory. You view the tc Server 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 Server instances are listed as platform-resource tc Server single-catalina-base-dir, and standard Apache Tomcat servers as Tomcat X.X.
8.
 
In the table, click on the tc Server you just added to the AMS inventory, as shown in the following graphic.
 
AMS displays the configuration and management pages of a tc Server instance, as shown in the next graphic. See the explanation after the graphic for details about the highlighted sections.
 
 
The Monitor tab displays monitoring information about a tc Server instance and its services, such as the deadlocks detected, available free 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.
 
The Inventory tab allows you to view and manage tc Server's general properties, the services hosted by the server, groups containing the server, and the server's monitoring and control configuration.
 
The Alerts tab allows you to view, configure, and create alerts for a tc Server instance. For example, tc Server comes pre-configured with a alert that detects when thread deadlocks have ocurred in a server.
 
The Control tab allows you start, stop, and restart this tc Server instance, as well as schedule one of these actions for a future date.
 
The Views tab is further divided into two tabs: Server Configuration and Application Deployment. The server configuration tab allows you to configure the tc Server 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 Server instance, as well as start, stop, reload, and undeploy already deployed Web applications.
9.
 
Click the Inventory tab.
10.
 
Click the Configuration Properties section, as shown in the following graphic; see the section after the graphic for an explanation of this page and when you might need to update the values.
 
AMS uses the values of the fields in this section to connect to the tc Server instance, control it, and so on. In particular, the Shared section specifies the JMX properties of the tc Server instance; AMS uses JMX to configure and manage tc Servers. If you have not changed the JMX values in server.xml, AMS will populate these fields automatically, so the tc Server instance should work with AMS without change. However, if you have changed the JMX values of your tc Server by manually updating its server.xml file, then you must change the corresponding fields in AMS, as described in the following procedure.
a.
 
Click Edit.
 
b.
 
Update the following fields as required:
 
jmx.url: The URL that AMS uses to connect to the JMX server associated with the tc Server instance. The URL's 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 AMS) and that the value of jmxport is the value of the port attribute of the <Listener> element in the tc Server's server.xml file that corresponds to the com.springsource.tcserver.serviceability.rmi.JmxSocketListener class (default value is 6969).
 
jmx.username: The JMX username that AMS uses to connect to the JMX server associated with the tc Server instance. The username is stored in the file pointed to by the passwordFile attribute of the <Listener> element in the tc Server'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: The 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.
c.
 
Click OK.
You are now ready to monitor and configure the tc Server instance, as well as other resources such as Apache Tomcat. For a tutorial that describes how to perform common management and configuration tasks using AMS, see Tutorial: Using AMS to Configure and Manage tc Server.
For detailed conceptual and task information about using AMS, click the Help button on the AMS console.
Deploying Applications to tc Server
Deployment refers to the process of installing a Web application into the tc Server. This section describes two ways to deploy Web applications to the tc Server application server.
 
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 tc Server. 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, tc Server deploys and starts it and users can immediately start using the application. See the procedure below for details.
 
Dynamic deployment using AMS: The AMS console 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 Server instances and then deploy a WAR file to the group; AMS 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 Server individually, saving you much time if you have many servers in your environment.
See Tutorial: Using AMS to Configure and Manage tc Server for a tutorial that describes how to deploy applications to single tc Server instances, create tc Server 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 tc Server 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/tcServer-6.0/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/tcServer-6.0/myserver/webapps
You configure the deployment directory using the appBase attribute of the <Host> element that configures the virtual host for your tc Server. For additional details about static deployment, see Tomcat Web Application Deployment.
Uninstalling tc Server: Typical Steps
This section describes how to uninstall tc Server. It is divided into the following sections for each component of tc Server; you can uninstall one or all 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.
AMS Server
To uninstall the AMS server component of tc Server:
1.
 
If currently running, stop the AMS server. See Starting and Stopping the AMS Server and Agents.
2.
 
Start a terminal window (Unix) or command prompt (Windows).
3.
 
Windows only. If you installed the AMS server as a Windows service, change to the AMS_SERVER_INSTALL_DIR\bin directory (where AMS_SERVER_INSTALL_DIR refers to the directory in which you installed the AMS server, such as c:\home\tcserver\server-2.0.0) and uninstall the service using the following command:
prompt> cd:\home\tcserver\server-2.0.0\bin prompt> ams-server.exe -u
4.
 
Remove the directory in which you installed the AMS server, such as /home/tcserver/server-2.0.0:
prompt$ cd /home/tcserver prompt$ rm -rf server-2.0.0
AMS Agent
To uninstall the AMS agent component of tc Server:
1.
 
If currently running, stop the AMS agent. See Starting and Stopping the AMS Server and Agents.
2.
 
Start a terminal window (Unix) or command prompt (Windows).
3.
 
Windows only. If you installed the AMS agent as a Windows service, change to the AMS_AGENT_INSTALL_DIR directory (where AMS_AGENT_INSTALL_DIR refers to the directory in which you installed the AMS agent, such as c:\home\tcserver\agent-2.0.0) and uninstall the service using the following command:
prompt> cd:\home\tcserver\agent-2.0.0 prompt> ams-agent.exe -u
4.
 
Remove the directory in which you installed the AMS agent, such as /home/tcserver/agent-2.0.0:
prompt$ cd /home/tcserver prompt$ rm -rf agent-2.0.0
tc Server Application Server
To uninstall the tc Server application server:
1.
 
If currently running, stop all tc Server instances. See Starting and Stopping tc Server Instances.
2.
 
Start a terminal window (Unix) or command prompt (Windows).
3.
 
Windows only. If you installed the tc Server instance as a Windows service, change to the CATALINA_BASE\bin directory (such as c:\home\tcserver\tcServer-6.0\myserver\bin and uninstall the service using the following command:
prompt> c:\home\tcserver\tcServer-6.0\myserver\bin prompt> tcserver-ctl.bat uninstall
4.
 
Remove the CATALINA_HOME directory of the tc Server you want to remove. For example:
prompt$ rm -rf /home/tcserver/tcServer-6.0
Depending on how you have installed and configured tc Server, this step might also delete all tc Server application server instances, especially in the case where CATALINA_HOME equals CATALINA_BASE, which is true by default with the ASF layout of tc Server. In the SpringSource layout of tc Server, however, the directories that correspond to particular tc Server instances are not by default under CATALINA_HOME.
5.
 
If you want to remove all tc Server instances (corresponding to CATALINA_BASE), and the preceding step did not do it, simply remove the relevant CATALINA_BASE directories. For example, the SpringSource layout of tc Server puts the new tc Server instances in their own directory parallel to the CATALINA_HOME directory.
You might, however, have created your tc Server instances in another location; if so, remove the corresponding directory.
Upgrade and Migration Guide
NOTE: It is assumed in this topic that you have an existing tc Server installation, along with one or more tc Server instances, and you want to upgrade it to the latest version of tc Server. If you are installing tc Server for the first time, see Installing tc Server: Typical Steps for details.
This topic describes how to perform the following supported upgrade and migration use cases:
 
 
Upgrading a tc Server Installation to the Latest Version
The procedure in this section describes how to upgrade a tc Server installation to version 6.0.20.C from any of the following versions:
 
6.0.19.A
 
6.0.20.A
 
6.0.20.B
The tc Server upgrade procedure can be conceptually broken up into the following sub-tasks:
 
Upgrade your current AMS server to the new version included in version 6.0.20.C of tc Server (2.0.0.SR04). This step migrates all the data from the previous version of the AMS server, such as discovered resources and alert settings, to the new version of AMS server. You use the install.sh script to perform this sub-task.
 
Install the AMS agent included in version 6.0.20.C of tc Server (2.0.0.SR04). No specific upgrade is required for the AMS agent. You use the install.sh script to perform this sub-task.
 
Install the 6.0.20.C tc Server application server component alongside the previous version. You use the install.sh script to perform this sub-task.
 
Upgrade existing tc Server instances to version 6.0.20.C. You use the tcserver-instance.sh script to perform this task.
Depending on how you have configured your entire tc Server installation, you might perform different sub-tasks on different computers. For example, on the computer on which you have installed the AMS agent and application server component (called a managed node), you perform sub-tasks 2, 3, and 4. However, on the computer on which you installed the AMS server (and nothing else), you perform only task 1. However, for simplicity, the following procedure assumes that you have install all three components (AMS server, AMS agent, and application server) on the same computer and thus discusses all sub-tasks. Make the appropriate changes to the procedure to fit your particular environment.
The examples in this section use Unix sytax; 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.
To upgrade your tc Server installation to 6.0.20.C, follow these steps:
1.
 
Shut down all currently running tc Server components (AMS server, AMS agent, and all tc Server instances.)
2.
 
Read Overview of Installation for a discussion of the different tc Server distribution files and Important Note When Installing on Unix Platforms if you are upgrading on Unix.
3.
 
Download the appropriate tc Server distribution from the SpringSource Customer Account Portal.
4.
 
Unzip or untar the tc Server distribution file into a temporary directory. Be sure the owner of the temporary directory is the same as the user that unzips/untars the distribution file, or you will get an error when you run the installer program.
On Windows, the distribution is a self-extracting JAR file that you can expand using Windows Explorer by double-clicking on it; the file unzips in the same directory in which it is located. NOTE: Internet Explorer recognizes that the downloaded distribution file is actually formatted as a ZIP file, and by default might change its file extension from .jar to .zip. This means that if you used IE to download the distribution file and its file extension changed, you might not be able to simply double-click on it to extract its contents. If this is the case, you can either use a zip extractor program, such as 7-Zip, to extract the files, or rename the file to have a .jar extension.
On Unix, use the tar command to extract the files. For example, to untar the file in the current directory and assign the extracted files to the same group as the user executing the command:
prompt$ tar --no-same-owner -xvfz /home/tarfiles/tcserver-6.0.20.C-GA-linux32.tgz
5.
 
Start a command prompt (Windows) or a terminal (Unix.)
6.
 
64-bit Unix platforms only. If you are upgrading tc Server on a 64-bit computer, you must explicity set the JAVA_HOME environment variable to point to a 64-bit JVM or JRE. You must also ensure that your PATH environment variable includes this 64-bit JAVA_HOME/bin directory, and that it appears before any other non-64-bit JVM/JRE. This step ensures that you are able to upgrade/install all available components of tc Server (application server and AMS server/agent.)
Use the which java Unix command to ensure your PATH variable points to the 64-bit JVM/JRE:
prompt$ which java /usr/java64/jdk1.6.0_11/bin/java
7.
 
Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script. For example, on Unix:
prompt$ cd /home/springsource/tcServertmp prompt$ ./install.sh
The installer program performs some checks of your system then displays a menu of options. Depending on the components that are available in the distribution, as well as the components you want to upgrade or install on your computer, pick one, two, or all of the following procedures marked in bold:
Note that you must run the install.sh script from the directory in which it lives, and not from any other directory, or you will get an error.
8.
 
To upgrade the AMS server, follow these steps:
a.
 
Enter the number for the Upgrade tc Server AMS (Server) option at the Enter number: prompt.
b.
 
Enter the full pathname of the directory that contains the previous version of the AMS server. This is the directory that contains the AMS server sub-directories such as bin, data, hq-engine, and so on. An example of an AMS server pathname is /home/tcserver/server-2.0.0.SR02.
c.
 
Enter the full pathname of the directory in which you want to install the new version of the AMS server. If, for example, you want to install the new AMS server alongside the one mentioned in the preceding step, enter /home/tcserver.
> Important: The specified directory must already exist; the install program does not create it for you.
The install program creates a directory under this main AMS server directory for the new server, such as /home/tcserver/server-2.0.0.SR04. The install program then migrates all the data in the old version of the AMS server to the new version.
d.
 
When the upgrade of the AMS server is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)
9.
 
To install the new version of the AMS agent, follow these steps:
a.
 
Enter the number for the Install tc Server AMS (Server/Agent) - Quick Setup option at the Enter number: prompt.
The install program performs some checks of your system and then prints the AMS installation menu.
b.
 
Enter option #2 to install SpringSource AMS Agent.
c.
 
Enter the full pathname of the directory in which you want to install the new version of the AMS agent.
Important: The specified directory must already exist; the install program does not create it for you.
You can specify the same directory in which you installed the previous version of the AMS agent, such as /home/tcserver. The install program creates a directory under this main AMS installation directory for the AMS agent, such as /home/tcserver/agent-2.0.0.SR04.
d.
 
When the installation of the AMS components is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)
10.
 
To install the new version of the tc Server application server, follow these steps:
a.
 
Enter the number for the Install tc Server Application Server option at the Enter number: prompt.
b.
 
Enter the full pathname of the directory into which you want to install the new version of the tc Server application server component.
> Important: The specified directory must already exist; the install program does not create it for you.
SpringSource recommends that you enter the same directory in which you installed the previous version of the application server component.
For example, if you originally installed version 6.0.20.A of tc Server in the /home/tcserver directory, the installer program created a directory called /home/tcserver/tcServer-6.0/tomcat-6.0.20.A that contains the Tomcat binaries, etc. When you install version 6.0.20.C, you should also specify that the tc Server application server component be installed in /home/tcserver so that the installer program creates a directory called /home/tcserver/tcServer-6.0/tomcat-6.0.20.C.
Installing 6.0.20.C in this way overwrites the following tc Server command scripts from the previous version in the top-level directory: tcserver-instance.sh and tcserver-ctl.sh, along with their supporting JAR files in the tijars directory. This is by design. The installation does not overwrite any other files or directories. If, however, you want to backup these command scripts in case you need to revert to the previous release, be sure to do that before installing the latest release.
11.
 
Enter the indicated number to exit when you have finished upgrading and installing all the required components for this computer.
12.
 
The remainder of this procedure describes how to upgrade the version of tc Server instances to 6.0.20.C.
Open a terminal (Unix) or command window (Windows) and change to the INSTALL_DIR/tcServer6.0 directory, where INSTALL_DIR is the main installation directory such as /home/tcserver:
prompt$ cd /home/tcserver/tcServer6.0
By default, all tc Server instances are located in this directory in their own directory, such as myserver.
13.
 
For each previous-version tc Server instance you want to upgrade, run the following command:
prompt$ ./tcserver-instance.sh -s instance -m -v 6.0.20.C
where instance refers to the name of the sub-directory that contains the tc Server instance you want to upgrade. For example, if you want to upgrade the tc Server instance myserver, run the following command:
prompt$ ./tcserver-instance.sh -s myserver -m -v 6.0.20.C
14.
 
Start the instance as described in Starting and Stopping tc Server Instances. The startup messages should indicate that the instance is now using version 6.0.20.C of tc Server. The messages should look similar to the following:
prompt$ ./tcserver-ctl.sh 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.20.C INFO Tomcat Version: 6.0.20.C INFO tcServer Version: 6.0.20.C-GA Using CATALINA_BASE: /home/tcserver/tcServer-6.0/myserver Using CATALINA_HOME: /home/tcserver/tcServer-6.0/tomcat-6.0.20.C Using CATALINA_TMPDIR: /home/tcserver/tcServer-6.0/myserver/temp Using JRE_HOME: /home/java/jdk1.6.0_11
When you complete this procedure for all components on all computers, you will have successfully upgraded your full tc Server installation.
You should now start the new versions of the AMS server and agent rather than the old versions; for details see Starting and Stopping the AMS Server and Agents. The new version of the AMS server will contain all data from the old version, such as discovered resources and alert information. Note that when you start the new version of the AMS agent, the script requests information about the AMS server to which it will communicate. Be sure to enter the information for the upgraded AMS server. This is a one-time event and subsequent starts of the agent do not require this input.
Migrating from SpringSource ERS
This section is for users who want to migrate an existing ERS 4.0 instance to tc Server 6.0.20.C. It is assumed that you have already installed version 6.0.20.C; if not, see Installing tc Server: Typical Steps.
For clarity, the migration procedure will use the following sample data; adjust the examples to fit your own environment accordingly. It is assumed that:
 
ERS 4.0 is installed 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.
 
The application server component of tc Server 6.0.20.C is installed in /home/tcserver/tcServer-6.0.
The examples use Unix sytax; if you are migrating on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script.
To migrate an existing ERS server instance, follow these steps:
1.
 
If the ERS instance you want to migrate is running, stop it. See the ERS documentation for details.
2.
 
Open a terminal (Unix) or command window (Windows).
3.
 
Copy the existing ERS 4.0 server instance directory to the tc Server application server installation directory. For example:
prompt$ cp -r /opt/ers40/servers/ers-instance /home/tcserver/tcServer-6.0
4.
 
Edit the /home/tcserver/tcServer-6.0/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 Server application server home directory. In our example, this would be /home/tcserver/tcServer-6.0.
 
tomcat_dir: Points to the directory that contains the Tomcat binaries. In our example, this would be $root_dir/tomcat-6.0.20.C.
 
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.
5.
 
Windows Only: Edit the /home/tcserver/tcServer-6.0/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 Server application server home directory. In our example, this would be /home/tcserver/tcServer-6.0.
 
wrapper.tomcat_home: Points to the directory that contains the Tomcat binaries. In our example, this would be $(ers.home)\tomcat-6.0.20.C.
 
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.
6.
 
Start the instance using the same ERS start script you have always used (tomcat_startup.sh, located in the /home/tcserver/tcServer-6.0/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 be using tc Server 6.0.20.C binaries.
Tutorial: Using AMS to Configure and Manage tc Server
This tutorial provides an overview of the basic steps for using the AMS administration console to configure and monitor tc Server and manage applications deployed to tc Server.
It is assumed that you have already installed and started the components of tc Server (AMS server and agent and at least one instance of the tc Server application server) and that you have invoked the AMS console in your browse and have logged in using the administration username/password (default hqadmin/hqadmin) or as an AMS user who has been given the permissions to configure tc Server. If this is not the case, see the following sections:
 
 
 
 
Most AMS console pages have a Help link at the top-right corner that provides detailed information about using AMS. Additionally, the tc Server configuration pages include a icon that you can click to get information about the fields on the configuration pages.
Follow these high-level steps for a brief overview of using AMS to manage and configure tc Server; click on a particular step to see a detailed procedure:
1.
 
2.
 
3.
 
4.
 
5.
 
6.
 
7.
 
Restarting the tc Server Instance
The following procedure shows how to restart a currently running tc Server instance. If you need navigational help for the first few steps, see Getting Started with the AMS Console.
1.
 
Click the Resources > Browse link at the top of the AMS console to browse for your tc Server instances.
2.
 
Click the Servers(X) link to see the list of servers known by AMS. To limit the number of displayed servers to just tc Server, select SpringSource tc Server 6.0 from the View drop-down list to view just tc Server instances.
3.
 
In the table, click the tc Server you want to restart. The server will be listed as platform-resource tc Server single-catalina-base-dir, where platform-resource refers to the computer hosting the tc Server instance and single-catalina-base-dir refers to the CATALINA_BASE directory of the tc Server instance without the leading directory pathnames, such as myserver.
4.
 
Click the Control tab. You use this AMS console page to stop, start, and restart the current tc Server 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.
 
Right after you click the restart button, the Command State field in the Current Status section says In progress until the tc Server instance has been succesfully restarted. The Current Status section always displays information about the last control action; in this case the restart of the tc Server instance.
Configuring tc Server
The following procedure shows how to make a few simple configuration changes to the current tc Server instance. In particular, it shows how to change a startup-up JVM option (maximum heap size) and how to change the working directory of the tc Server instances's default virtual host.
It is assumed in this procedure that you have already browsed to the tc Server that you want to configure, as described in Restarting the tc Server Instance.
1.
 
Click the Views > Server Configuration tab, as shown:
 
This brings you to the set of pages for configuring the current tc Server instance. The pages are divided into three tabs:
 
Configuration: For configuring tc Server startup options, JVM options, context information for all deployed Web applications, default behavior of JSPs and static content, and so on.
 
Resources: For configuring or creating JDBC datasources.
 
Services: For configuring or creating tc Server 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 Memory section on the right, enter 1024 in the Max Heap Size (MB) field.
4.
 
Click the Save button, located at the bottom of the page.
The message Configuration saved successfully appears at the top, as shown in the following graphic. This means that AMS 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 Server configuration files, such as CATALINA_HOME/bin/setenv.sh (in this case) or CATALINA_BASE/conf/server.xml, or to undo the changes.
 
AMS displays this box until you save or undo, although you can keep making additional changes before you pick one. In this tutorial, we will 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 Server.
 
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 dirctories are created under CATALINA_BASE.
8.
 
Click the Save button located at the bottom of the page.
The message Configuration saved successfully appears in the top.
NOTE: When you update the tc Server configuration using the AMS console, if the property you are updating was previously specified as a variable (such as ${jmx.port}), tc Server replaces that variable with the actual value in the server.xml file. This means, for example, that port="${jmx.port}" would become port="6954". Note that the variable will still be set in the catalina.properties file to the old value, but the tc Server server does not actually use it because the property is now hard-coded 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 the Push Changes to Server button.
11.
 
In the box at the top, click the restarted link to restart tc Server so that the changes take effect.
 
12.
 
Click Restart Server.
The message Server Restarted appears at the top.
Deploying and Managing Applications
The following procedure shows how to deploy a new Web application to tc Server, 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 in this procedure that you have already browsed to the tc Server to which you want to deploy, as described in Restarting the tc Server Instance.
1.
 
Click the Views > Application Management tab. You use this page to deploy and manage tc Server 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, however, the Web application is actually located on the computer on which the tc Server instance is running, then go to the Deploy Application from Server Machine section. A typical remote machine use case is when machines use network mounted drives to which they have access.
Enter the location of the Web application in the corresponding field. You can use the Browse button to find a local Web application WAR file; you must, however, already know the full pathname of the WAR file if you are deploying it from the tc Server computer. Additionally, 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 new_context in the Context path field.
4.
 
Click Upload and deploy (for a local WAR file) or Deploy (for deploying a WAR file on the tc Server computer). AMS deploys the WAR file to the current tc Server. 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/new_context
where:
 
host refers to the name of the computer on which the tc Server instance is running. If it is the same computer as your browser, you can enter localhost.
 
port refers to the TCP/IP port to which the tc Server instance listens. The default value is 8080.
You can get the host and port information of a tc Server instance by looking at its HTTP connector configuration from the Views > Server Configuration > Services tab.
Adding tc Server Instances to the Favorite Resources Portlet
The main AMS dashboard includes a Favorite Resources portlet that lists the resources you most often manage. When you first install AMS, 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 go back to it again and again. The following procedure shows how to add a tc Server instance to he Fvorite Resources portlet.
1.
 
Navigate to the tc Server instance, as described in the first three steps of Restarting the tc Server Instance.
2.
 
Click the Tools Menu in the top-right corner and chose the Add to Dashboard Favorites link.
 
3.
 
The tc Server instance shows up in the Favorite Resources portlet on the main dashboard:
 
Creating a Tomat Server Group
The following procedure describes how to create an AMS group of multiple tc Server instances. You can then deploy a Web application to the group using a single procedure similar to Deploying and Managing Applications; AMS then 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 using a single procedure similar to Restarting the tc Server Instance.
Using AMS groups can save you a great deal of time if you need to control multiple tc Server 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 Server instances running and that you have added them to the AMS inventory. See Creating a New tc Server Instance for details.
1.
 
Click the Resources > Browse link at the top of the AMS Console.
2.
 
Click the Servers (X) link to list all the servers in your resource inventory. The tc Server instances are listed as server type SpringSource tc Server 6.0 and standard Apache Tomcat servers are listed as Tomcat X.X
3.
 
For each tc Server you want to include in the new group, check the box to the left of the server's entry in the table.
4.
 
Click Group.
The following graphic shows how to group together two tc Server instances called tc Server anotherserver and tc Server myserver.
 
5.
 
Enter a name for the group, such as tcServerGroup and an optional description and location.
6.
 
Click OK.
Depending on the members of the group, AMS creates a Compatible Group/Cluster or Mixed Group. The first type of group consists of a single type of server, such as only tc Servers or only Apache Tomcat servers. The second mixed group consists of different types of servers, such as both tc Servers and Apache Tomcat servers.
To stop/restart the group of servers, or deploy an application to the group, you simply browse to the group, as described in the following steps:
1.
 
Click Resources > Browse at the top of the AMS console.
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/start all the servers in the group, click the Control tab, then follow the same steps as if you were controlling a single server; see Restarting the tc Server Instance. Note that the breadcrumbs at the top of the console page list the group name (tcServerGroup in this case) rather than the tc Server instance name.
5.
 
To deploy and manage applications on all servers in the group, click the Views > Application Management tab, then follow the same steps as if you were deploying or managing the applications of a single server; see Deploying and Managing Applications.
Note: In this release of tc Server, you cannot update the configuration of a group of tc Server instances using the Views > Server Configuration tab.
Monitoring tc Server
As soon as you add a resource, such as a tc Server, to the AMS inventory, AMS begins collecting a variety of metrics about the resource that you can use to monitor its state and health. AMS displays the values of the metrics over a specified period of time using indicator charts or tables.
Examples of the types of metrics that AMS collects about tc Server include:
 
The number of thread deadlocks detected.
 
The size of the free physical memory.
 
The JSP count per minute.
 
The number of servlet requests per minute.
You can create an alert for a resource that fires when a specified condition is met, and optionally specify a control action that happens when the alert is fired. AMS is pre-configured for a deadlock detection alert; see Manage the Pre-Configured Deadlock Detected Alert for a procedure that shows how to take a look at it, change it, and then disable it.
The following procedure describes how to view the monitoring metrics for a tc Server instance.
1.
 
Navigate to the tc Server instance, as described in the first three steps of Restarting the tc Server Instance.
2.
 
Click the Monitor tab.
The charts under the Indicator tab show data about the entire tc Server, such as thread deadlocks detected and size of the free physical memory and swap space. 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 Server instance, such as the JSP and servlet monitors.
3.
 
In the Services table, click SpringSource tc Server 6.0 JSP Monitor. The chart on the right shows usage metrics about the JSPs deployed to tc Server.
You can now click on other services within the Monitoring tab to view other monitoring information for the tc Server instance.
Manage the Pre-Configured Deadlock Detected Alert
AMS includes a pre-configured alert that triggers once if the Deadlocks Detected metric exceeds 0. AMS applies this alert to all auto-discovered tc Server instances, enables it by default, and then checks the metric every minute to see if the condition has been met. After triggering, AMS disables the alert until an administrator marks it as Fixed.
The following procedure describes how to view this pre-configured alert, modify it so that AMS automatically restarts the tc Server instance in which the alert is triggered, and then disable it.
1.
 
Navigate to the tc Server instance, as described in the first three steps of Restarting the tc Server Instance.
2.
 
Click the Alert tab at the top of the page. This page displays a table of alerts that have been defined for this tc Server. You should see the pre-configured Deadlocks Detected alert; by default it is active (enabled.)
 
3.
 
In the table, click Deadlocks Detected. This brings you to the Alert Defintion page.
4.
 
In the Control Action section, click the EDIT... button.
 
5.
 
Select restart from the Control Type drop-down list.
 
6.
 
Click OK. You have just modified the alert so that AMS automatically restarts the affected tc Server instance in the case of a deadlock detection.
7.
 
To disable the alert, follow these steps:
a.
 
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.
b.
 
In the table, select the Deadlocks Detected alert by checking the box to the left of its name.
c.
 
At the bottom of the table, choose No in the Set Active drop-down list.
 
d.
 
Click the arrow to the left of the drop-down list. The Active column for the Deadlocks Detected alert changes to No.
Tutorial: Very Simple Web Application Development
Before you work through this tutorial, be sure you install SpringSource tc Server. See Installation Overview.
This tutorial is intended for programmers who have never before created a Web application and want to know the basics of creating servlets and JSPs, how to package them into a deployable WAR file, how to deploy the application to the tc Server application server , and finally how to run the application in a browser.
The tutorial uses Ant as its build framework. You can also use an IDE, such as SpringSource Tool Suit, 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.
1.
 
If not already installed, install Ant on your computer. You can download the build tool from the Apache Ant Project.
Follow the installation instructions in the Ant distribution. Be sure you 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. SpringSource tc Server includes a full JDK that you can use if you haven't already installed your own.
3.
 
Create the project directory structure that will contain the HelloWorld Web application source files.
First 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). Then 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 the HelloWorld servlet is in.
In the web directory, create two sub-directories: images, which will obviously 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 5. Directory Hierarchy of the HelloWorld Application
 
4.
 
Create the Hello.java servlet Java source file and put it in the helloworld/src/examples directory.
See Hello.java for sample Java code that you can copy and paste into your own Java file as well as a brief explanation of how to program a simple servlet.
5.
 
Create the hello.jsp JSP file and put it in the helloworld/web directory.
See hello.jsp for sample JSP code that you can copy and paste into your own JSP file as well as a brief explanation of how to program a simple JSP.
6.
 
Create the web.xml Web application deployment descriptor and put it in the helloworld/web/WEB-INF directory.
See web.xml for sample XML that you can copy and paste into your own web.xml file as well as a brief explanation of what these elements mean.
7.
 
Create the default index.html page and put it in the helloworld/web directory.
See index.html for a sample HTML file that you can copy and paste into your own file.
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.
See build.xml for a sample Ant build file that you can copy and paste into your own file.
In your own build file, be sure you update the tcserver.home property to fit your environment; it should point to the CATALINA_HOME of your tc Server installation. For example, if you installed tc Server in the /home/tcserver directory, then you should set the tcserver.home property in the build.xml file as follows:
<property name="tcserver.home" value="/home/tcserver/tcServer-6.0/tomcat-6.0.20.C" />
9.
 
Right click the following image and save it with name springsource.png to the helloworld/web/images directory.
 
When you have finished 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
10.
 
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 helloWorld-0.1-dev.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: c:\tcserver_docs\samples\helloworld\dist [mkdir] Created dir: c:\tcserver_docs\samples\helloworld\work\WEB-INF\classes [copy] Copying 4 files to c:\tcserver_docs\samples\helloworld\work compile: [javac] Compiling 1 source file to c:\tcserver_docs\samples\helloworld\work\WEB-INF\classes dist: [jar] Building jar: c:\tcserver_docs\samples\helloworld\dist\helloWorld-0.1-dev.war all: BUILD SUCCESSFUL Total time: 0 seconds
11.
 
Start tc Server instance. See Starting and Stopping tc Server Instances for details.
12.
 
Deploy the Web application JAR file to tc Server. See Deploying Applications to tc Server for details.
13.
 
Invoke the HelloWorld Web application in your browser using the following URL:
http://host:port/helloWorld-0.1-dev/
where:
 
host refers to the name of the computer that is hosting tc Server. If it is the same as the computer hosting your browser, you can use localhost.
 
port refers to the port to which tc Server listens. The default value is 8080.
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.
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 Server 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.
Sample web.xml File
The following sample web.xml deployment descriptor shows how to declare the HelloServlet servlet in the Helloworld Web application: see Description of the web.xml File for additional information:
<?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
The preceding web.xml deployment descriptor file includes the <servlet> XML element that declares the HelloServlet and specifies the Java class that implements the servlet (examples.Hello) and the <servlet-mapping> XML element that specifies the URL pattern that invokes the servlet in a browser (/hello). This URL pattern is used in the index.html file.
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>
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="helloWorld"/> <property name="app.version" value="0.1-dev"/> <property name="tcserver.home" value="/home/tcserver/tcServer-6.0/tomcat-6.0.20.C" /> <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}-${app.version}.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.
Troubleshooting
The following sections describe common problems and ways to resolve them.
 
 
 
AMS: Resources Not Showing up in the AMS Server Console
By default, an AMS agent checks for new resources only once a day. This means that, for example, if you start the AMS server and agent, and then create a new tc Server instance and start it, you might have to wait a maximum of 24 hours for the new tc Server instance to be auto-discovered by AMS. There are two ways you can force an auto-discovery of new resources on your platform:
 
Stop and start the AMS agent on the computer for which you want to force an auto-discovery. When the AMS agent starts, it automatically checks for new resources. See Starting and Stopping the AMS Server and Agents for details.
 
Use the AMS GUI to force an auto-discovery by following these steps:
a.
 
From the main dashboard, click the Resources > Browse link.
b.
 
Click the Platforms(XX) link.
c.
 
In the table, click on the name of the platform for which you want to force an auto-discovery.
d.
 
In the top-right Tools Menu box, click New Auto-Discovery.
e.
 
In the top section called Quick Auto-Discovery Scan, click the OK button.
Any new resources show up in the Auto-Discovery portlet of the main dashboard as soon as AMS completes the scan of the platform.
AMS: Errors When Trying to Add an Auto-Discovered Resource
If you get errors when trying to add an auto-discovered resource to AMS using the AMS console, try the following steps:
1.
 
Log onto the platform that hosts the resource that is returning errors when you try to add it using the AMS console.
2.
 
Stop the AMS agent. See Starting and Stopping the AMS Server and Agents for details.
3.
 
Change to the AMS_AGENT_INSTALL_DIR directory, where AMS_AGENT_INSTALL_DIR refers to the directory in which you installed the AMS agent, such as /home/tcserver/agent-2.0.0.
4.
 
Remove the data directory.
5.
 
Start the AMS agent. Because you removed the data directory, the agent thinks 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 correctly add all new auto-discovered resources using the AMS console GUI again.
tc Server: Hot Redeploy 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.
If you require the ability to perform a hot redeployment on Windows, then follow these steps:
1.
 
Update the CATALINA_BASE/conf/context.xml file of the tc Server 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 impacts 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 will significantly impact startup time of applications, 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 Server instance for the change to take affect.
Setting these two attributes to true forces tc Server to copy files rather than read them in place. This also means that if you try to copy in a new .jsp file directly, tc Server does not pick it up.
For more information and warnings about configuring the context.xml file, see The Context Container.