Getting Started with vfabric tc Server

Transcription

1 Getting Started with vfabric tc Server VMware vfabric Cloud Application Platform 5.0 VMware vfabric tc Server 2.6 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see EN

2 You can find the most up-to-date technical documentation on the VMware Web site at: support. The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: Copyright 2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. VMware, Inc., 3401 Hillview Avenue, Palo Alto, CA

3 Table of Contents 1. About Getting Started with vfabric tc Server... 1 Intended Audience Quick Start Overview of tc Server... 5 Usability Enhancements to Apache Tomcat... 5 Easy Configuration and Monitoring with the Hyperic tc Server Plug-In... 5 Agile Application Development with Spring Insight Developer... 6 Application Cluster Monitoring with Spring Insight Operations... 6 Enhanced Diagnostics... 7 tc Server Command-Line Interface and Scripts... 7 tc Server Editions... 7 How tc Server and Hyperic Work Together... 9 Related Documentation Comparing tc Runtime and Apache Tomcat Standard Application Server Features Enterprise Application Server Features Advanced Configuration Features Operations Features Installing vfabric tc Server Meeting System Software Requirements for tc Server Installing tc Server as Part of vfabric Cloud Application Platform Install tc Server Developer Edition Install tc Server Standard Edition (tc Runtime Only) Install tc Server Standard Edition and Hyperic Management Components Activate a Local vfabric tc Server License Overview of tc Server Directories, Variables, and Configuration Files Enabling Bash Completion for tc Server Scripts Setting Up Unix Users for tc Server and Hyperic Post-Installation Tasks Creating a New tc Runtime Instance Starting and Stopping tc Runtime Instances Windows: Installing the Hyperic Server and Agents as Windows Services Starting and Stopping the Hyperic Server and Agents Getting Started with the Hyperic User Interface Deploying Applications to tc Runtime Instances Uninstalling tc Server: Typical Steps Upgrade and Migration Guide Upgrading a 2.0.X, 2.1.X, or 2.5.X tc Server Installation to Upgrading a 2.6.X tc Runtime to the Latest Version Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances Before You Begin Restart a tc Runtime Instance Reconfigure a tc Runtime Instance Deploy a Web Application to a tc Server Runtime Instance Add tc Runtime Instances to the Favorite Resources Portlet Create an Hyperic Group of Multiple tc Runtime Instances Monitoring tc Runtime Instances Manage the Preconfigured Deadlock Detected Alert Tutorial: Very Simple HelloWorld Web Application Before You Begin Creating and Deploying the HelloWorld Web Application Java Source of the Hello.java Servlet VMware vfabric tc Server 2.6 iii

4 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... Hyperic: Resources Not Showing up in the Hyperic User Interface... Hyperic: Errors When Trying to Add an Auto-Discovered Resource... Hyperic Agent: Errors When Starting on Solaris... tc Runtime: Hot Redeploy/Stop/Undeploy on Windows Fails... tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite... tc Runtime: JVM Performing a Full GC... iv Getting Started with tc Server

5 About Getting Started with vfabric tc Server 1 1. About Getting Started with vfabric tc Server Getting Started with vfabric tc Server describes product concepts and provides setup instructions for VMware vfabric tc Server, a component of the VMware vfabric Cloud Application Platform. Read the documentation to learn how to create, start, and stop tc Runtime instances; deploy Web applications; and use the VMware vfabric Hyperic management tool to monitor tc Runtime instances. This documentation includes tutorials for creating and deploying a HelloWorld Web application and for using vfabric Hyperic with tc Server. Intended Audience Getting Started with vfabric tc Server is intended for anyone who wants to install, configure, and use tc Server to develop or to serve Web applications. VMware vfabric tc Server 2.6 1

6 2 Getting Started with tc Server 2 About Getting Started with vfabric tc Server

7 Quick Start 3 2. Quick Start This section provides quick start instructions for installing VMware vfabric tc Server Standard Edition, creating a tc Runtime instance, and starting the tc Runtime instance. tc Runtime is the runtime component of tc Server. If you are upgrading an existing tc Server installation, see the upgrade documentation. If you are installing tc Server Developer Edition, see Installing tc Server. If you obtain tc Server as part of vfabric Platform, first complete the license activation and installation procedures in Getting Started with vfabric Cloud Application Platform. Then follow the procedures here to install tc Server and create and start a tc Runtime instance. Install tc Server 1. Download and install a JDK or JRE on the computer on which you are installing tc Server. See Required Software: JDK or JRE. 2. Determine the user that is going to create and run the tc Runtime instances, and create it if necessary. Consider creating a user dedicated to tc Server tasks and disabling its interactive login for security purposes. On Unix, never run tc Runtime instances as the root user. See Setting Up Unix Users for tc Server and Hyperic. For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user. 3. Login to the computer on which you are installing tc Server as the appropriate user, such as tcserver. If you have disabled interactive login, login as the root user and use su - tcserver to become the user. 4. Open a terminal (Unix) or Command Prompt (Windows) and create a directory to contain the tc Runtime component (such as /opt/vmware) if it doesn't already exist. Unix example: prompt$ mkdir /opt/vmware Windows example: prompt> mkdir \opt\vmware 5. From the VMware Download Center, download the most recent vfabric-tc-server-standard-version.zip file and unzip the contents into the directory you created in the preceding step. The version in the zip file name is the version number, for example RELEASE. This is all that is required to install tc Runtime; there is no installer program. For example, in Unix, if you specified a directory called /opt/vmware in the preceding step and downloaded the Standard Edition file to your home directory: prompt$ cd /opt/vmware prompt$ unzip ~/vfabric-tc-server-standard release.zip In Windows Explorer, double-click the ZIP file you downloaded to launch the Windows Extraction Wizard and extract the file into the directory you created in the preceding step. After you unzip the ZIP file you will have a directory called /opt/vmware/vfabric-tc-serverstandard-version. This directory contains all the tc Runtime files and directories. VMware vfabric tc Server 2.6 3

8 4 Getting Started with tc Server Create and start a tc Runtime instance 1. From your terminal window or Command Prompt, change to the tc Runtime directory and execute the tcruntimeinstance command to create a basic tc Runtime instance (called myserver in the examples). VMware recommends that you use the --instance-directory option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the tcserver user can write to this directory and that the directory already exists. Unix example: prompt$ cd /opt/vmware/vfabric-tc-server-standard release prompt$./tcruntime-instance.sh create --instance-directory /var/opt/vmware/vfabric-tc-server-standard myserver Windows example: prompt> cd \opt\vmware\vfabric-tc-server-standard release prompt> tcruntime-instance.bat create --instance-directory \var\opt\vmware\vfabric-tc-server-standard myserver 2. (Windows only) Use the tcruntime-ctl command to make the new runtime instance a Windows service; use the -n option to specify the directory in which the instance is located: prompt> tcruntime-ctl.bat myserver install -n \var\opt\vmware\vfabric-tc-server-standard 3. Execute the tcruntime-ctl command to start the new tc Runtime instance; use the -n option to specify the directory in which the instance is located. Unix example: prompt$./tcruntime-ctl.sh myserver start -n /var/opt/vmware/vfabric-tc-server-standard Windows example: prompt> tcruntime-ctl.bat myserver start -n \var\opt\vmware\vfabric-tc-server-standard To confirm that the tc Runtime instance is running, invoke its welcome page in a browser. Use the URL where host is the name or IP address of the computer on which the tc Runtime instance is running (localhost if local). What to do next Read about tc Server features Install tc Server Developer Edition Install vfabric Hyperic to manage tc Runtime instances Read about options for creating tc Runtime Instances 4 Quick Start

9 Overview of tc Server 5 3. Overview of tc Server VMware vfabric tc Server is a Web application server based on open-source Apache Tomcat. It preserves the best of Tomcat and adds many mission-critical operational capabilities that are unavailable in the open-source product. tc Server harnesses the power of traditional JEE architectures and eliminates their complexity and performance drawbacks, making it easier, faster, and more cost-effective to build and run cloud-ready applications. With its lean architecture and small, 10MB memory footprint, tc Server requires significantly fewer resources than conventional servers, which allows for greater server density in virtual and cloud environments. Subtopics Usability Enhancements to Apache Tomcat Easy Configuration and Monitoring with vfabric Hyperic Agile Application Development with Spring Insight Developer Application Cluster Monitoring with Spring Insight Operations Enhanced Diagnostics tc Server Command-line Interface and Command Scripts tc Server Editions How tc Server and Hyperic Work Together Related Documentation Usability Enhancements to Apache Tomcat The tc Server runtime component, known as tc Runtime, offers usability advantages that make it easier, faster, and more flexible to configure and operate than Apache Tomcat. tc Runtime includes the following usability enhancements: Improved out-of-the-box configuration. In most cases, you can use tc Server immediately after you install it, with no additional configuration. Easy creation of a tc Runtime instance with the tcruntime-instance command script. You can leverage additional (optional) configuration features by specifying prepackaged templates when you create a tc Runtime instance, such as automatically configuring clustering or SSL. Easy and intuitive startup of a tc Runtime instance on both UNIX and Windows platforms. Default configuration of high-concurrency JDBC connection pool in new tc Runtime instances. For a detailed comparison of tc Server and Apache Tomcat features, see Comparing tc Runtime and Apache Tomcat. Easy Configuration and Monitoring with the Hyperic tc Server Plug-In Hyperic includes a tc Server plug-in that gives tc Server Standard Edition customers access to the Hyperic enterprise application management tool. Hyperic can manage and monitor tc Runtime instances, Spring-powered applications, and a variety of nonvmware platforms and application servers such as Apache Tomcat. The server instances and applications can be running on multiple computers. Hyperic provides a single console with powerful dashboards through which you can easily check the health of your applications. The Hyperic tc Server plug-in gives you the following capabilities: VMware vfabric tc Server 2.6 5

10 6 Getting Started with tc Server Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting a local or remote instance. Manage the lifecycle of a group of tc Runtime instances that are distributed over a network of computers. Configure a single instance of tc Runtime. Configuration options include the various port numbers to which the tc Runtime instance listens, JVM options such as heap size and enabling debugging, default server values for JSPs and static content, JDBC datasources, various tc Runtime connectors, and so on. Using the tcsadmin command-line tool, configure a group of tc Runtime instances. Deploy a Web application from an accessible file system, either local or remote. You can deploy to a single tc Runtime instance or to a predefined group of servers. Manage the lifecycle of applications deployed to a single tc Runtime instance or group of servers. Application lifecycle operations include start, stop, redeploy, undeploy, and reload. In addition to the preceding tc Runtime-specific Hyperic tasks, you perform the standard tasks : Inventory the resources on your network. Monitor resources. Receive alerts on problems with resources. The Hyperic plug-in includes a variety of preconfigured alerts. Control resources. Agile Application Development with Spring Insight Developer Spring Insight Developer, bundled with tc Server Developer Edition, makes it easy for application developers to observe the runtime behavior of Web applications. It allows you to see what is happening deep in the application, while it is running, with no required instrumentation. The visibility Spring Insight provides enables you to identify and solve problems quickly and to harden and tune the application by using readily available performance observations. Spring Insight Developer gives you the following capabilities: View the throughput, error rate, and response time for each application endpoint over time. View trace information for any recent request, revealing how much time the application spends in the following activities: Dispatching requests Executing JDBC queries Executing custom methods Mapping objects to database tables Rendering views Identify where and why exceptions occur. Identify which application components are busiest at any given time. Application Cluster Monitoring with Spring Insight Operations Spring Insight Operations enables administrators to monitor the real-time behavior and health of Web applications and the servers on which they are deployed. It gives the same deep visibility into applications as Spring Insight Developer, as well as the capability to view the information across a cluster or to drill down to any single server. 6 Overview of tc Server

11 Overview of tc Server 7 Whereas Spring Insight Developer runs within a single tc Server instance alongside the Web applications it analyzes, Spring Insight Operations has a distributed architecture. A single, dedicated tc Server instance runs the Spring Insight Dashboard. Each tc Server instance hosting applications in your cluster runs the Spring Insight Agent application. The Agents collect trace data and submit it to the Dashboard, where the information is compiled and rendered. This design minimizes the overhead Spring Insight adds to your production servers and makes it easier to secure the Dashboard. In addition to everything you can do with Spring Insight Developer, here are some things you can do with Spring Insight Operations: View graphs of the health, throughput, error rate, and response time for each application endpoint across the cluster, or drill down to individual servers. Visually identify failed or under-performing servers. See which servers are handling too much or too little of the load. Enhanced Diagnostics The following diagnostic features make it easy for you to troubleshoot problems with a tc Runtime instance and the applications that you deploy to tc Server: Thread diagnostics. When clients connect to a deployed Web application on a tc Runtime instance, they might occasionally encounter slow or failed requests. By default, tc Runtime logs errors in the log files; however, it is often difficult to pinpoint the exact source of the error and how to fix it. With thread diagnostics enabled, tc Runtime provides additional troubleshooting information. Deadlock detection. The tc Server Hyperic plug-in automatically detects whether a thread deadlock occurs in a tc Runtime instance or an application deployed to the instance. Time-in garbage collection.the tc Server Hyperic plug-in has a new metric that represents the percentage of process up time (0-100) that a tc Runtime instance spends in garbage collection. Tomcat JDBC datasource monitoring. A new tc Server Hyperic plug-in service represents the high-concurrency Tomcat JDBC datasources that you have configured for your tc Runtime instance. This service monitors the health of the datasource, such as whether its connection to the database has failed or was abandoned, and whether the JDBC queries that clients execute are taking too long. For some diagnostics features, the tc Server Hyperic plug-in includes one or more preconfigured alerts that make it easy for you to monitor the tc Runtime instance, as well as manage the various thresholds at which an alert is triggered. For additional information about these diagnostic features, and information about managing the associated Hyperic alerts, see "Managing tc Runtime-Related Hyperic Alerts" in vfabric tc Server Administration. tc Server Command-Line Interface and Scripts Use the command-line interface (CLI) tcsadmin to perform the following tasks: List servers, groups, and deployed applications. Deploy applications. Configure tc Runtime instances and groups. Control tc Runtime instances and groups. tc Server Editions tc Server is available in three different editions. tc Server Developer is geared towards the enterprise application developer. tc Server Standard is designed for operators and administrators. tc Server Spring Edition, a part of vfabric Cloud Application VMware vfabric tc Server 2.6 7

12 8 Getting Started with tc Server Platform 5.0, is for operators and administrators deploying tc Server enterprise applications on VMware vsphere and VMware ESXi hosts. Table 3.1. vfabric tc Server Editions Feature Developer Edition Standard Edition Spring Edition tc Runtime # # # Spring Insight Developer # # # vfabric Hyperic with tc Server Plug-In Spring Insight Operations # Elastic Memory for Java (EM4J) # Commercial Spring Support # The following sections describe the tc Server editions: Developer Edition Standard Edition Spring Edition Developer Edition The Developer Edition of tc Server is geared towards the application developer. It contains the tc Runtime; utilities to create and start tc Runtime instances; and a set of templates for creating specific preconfigured tc Runtime instances, such as cluster-node ready and SSL-enabled. This edition also includes Spring Insight Developer, an application that provides real-time visibility into the behavior and performance of user applications. The tc Server Developer Edition contains a template called insight that includes the Spring Insight application. You use this template to create new tc Runtime instances enabled with Spring Insight. See Spring Insight Developer for help setting up and using Spring Insight. tc Server Developer Edition includes Tomcat Web Application Manager, a web application you can use to deploy and manage tc Runtime applications. This edition does not include access to Hyperic Server and Agent. The Developer Edition is distributed as either a ZIP or compressed TAR file with the following names: vfabric-tc-server-developer-2.6.x.release.zip vfabric-tc-server-developer-2.6.x.release.tar.gz Standard Edition The Standard Edition of tc Server is for administrators and operators. Similar to the Developer Edition, the Standard Edition contains the tc Runtime, scripts to easily create and start tc Runtime instances, and templates to quickly create specific types of tc Runtime instances (such as cluster-node ready or SSL-enabled). This edition does not include Spring Insight Developer. With the Standard Edition, you have access to the vfabric Hyperic management system, which (as of version 4.6) includes the tc Server Hyperic plug-in in the general distribution. Install vfabric Hyperic if you want to use Hyperic to configure and manage the tc Runtime. If you do not want to use Hyperic to manage tc Runtime instances and want to use the tc Runtime on its own, install only the tc Runtime. The Standard Edition is distributed as either a ZIP or compressed TAR file with the following names: vfabric-tc-server-standard-2.6.x.release.zip 8 Overview of tc Server

13 Overview of tc Server 9 vfabric-tc-server-standard-2.6.x.release.tar.gz To download an evaluation of Hyperic, go to the VMware Downloads Center. Spring Edition The tc Server Spring Edition is part of vfabric Cloud Application Platform 5.0. It includes all of the components and features of tc Standard Edition, plus Spring Insight Operations, Elastic Memory for Java (EM4J) and Spring commercial support. Spring Insight Operations differs from Spring Insight Developer, which is included in the tc Server Developer Edition, in that it is designed to be used with an in-production system. It allows you to view real-time behavior and health of your production applications. You can see application behavior across all servers and drill down to see specific servers. With Spring Insight Operations, you create one tc Runtime Instance using the Insight Dashboard template. This instance contains the Spring Insight user interface. You create production tc Runtime instances with the Insight Agent template. The Agent template adds the ability to collect traces from your web applications and forward them to the Dashboard instance. EM4J improves memory management for Java applications running in VMs on an ESXi host. It works with a new ESXi 5.0 memory management interface to implement ballooning technology in the JVM. Because of the way Java manages its memory, it has been in the past best practice to give the JVM 100% of the memory it needs, while sizing the heap as small as possible to avoid wasting memory. This prevented VMs running Java applications from participating in all of the ESXi advanced memory sharing capabilities. EM4J establishes a balloon directory in the Java heap, freeing the memory for ESXi to share with other VMs that need it. EM4J encourages the JVM to use memory conservatively and helps applications behave predictably and gracefully as memory becomes scarce. It also makes it possible to over-commit memory, improving consolidation ratios for Java applications running on ESXi hosts. The tc Server Spring Edition is the same binary distribution as the Standard Edition, with licensing differences. The Spring Insight Operations Dashboard and Agent templates are separate downloads at the VMware Downloads Center. How tc Server and Hyperic Work Together tc Server standard edition, targeted to administrators, includes access to the Hyperic management capabilities. This section shows how the runtime component of tc Server (called the tc Runtime) and the Hyperic components (Hyperic Server and Hyperic Agents) work together, and possible configurations that you can install on one or more computers. The simplest installation is one in which you install all components (tc Runtime, Hyperic Agent, and Hyperic Server) on the same computer. The computer acts as a host for the tc Runtime instances and their deployed applications as well as a host to the Hyperic Server and Hyperic Agent, which are used to manage the tc Runtime instances. In the following figure, the Hyperic Server is managing one tc Runtime instance. Figure 3.1. Installing on One Computer Hyperic Server can, of course, manage multiple instances, and manage other kinds of servers. Because the tc Runtime instances are all on one computer, you only need to install one Hyperic Agent. This is illustrated in the following figure. VMware vfabric tc Server 2.6 9

14 10 Getting Started with tc Server Figure 3.2. Multiple tc Runtime Instances on One Computer You can create multiple tc Runtime instances on one computer and install Hyperic Server on another computer. One Hyperic Agent must be installed on any computer running one or more tc Server instances. You can create multiple tc Runtime instances on ComputerA, and install the Hyperic Server on ComputerB, as shown in the next figure. ComputerA is known as a managed node. Figure 3.3. Installing on Two Computers In another scenario, you host the Hyperic Server on computerb, but want to install tc Runtime on many computers, possibly of different platforms such as Unix and Windows. In this case you must also install the Hyperic Agent on each computer (managed node) that hosts the tc Runtime instances. In the following figure, for example, computerc might be a Windows platform while all the rest of the computers are Unix. Also note that each computer has a different set of tc Runtimes installed, but only one Hyperic Agent. In the figure, all computers except computerb are managed nodes. 10 Overview of tc Server

15 Overview of tc Server 11 Figure 3.4. Installing on Multiple Computers Related Documentation Because tc Runtime is based on Apache Tomcat, much information about the tc Runtime itself is provided by Apache. See the following documentation: Apache Tomcat 6.0 Documentation Apache Tomcat 7.0 Documentation Apache Tomcat FAQ The Hyperic management component of tc Server provides monitoring and management for your Web infrastructure. You can use it to streamline operations, manage infrastructure complexity, and drive service-level improvements. The Hyperic user interface includes online-help for generic Hyperic functionality and related tc Server functionality. The following links provide additional documentation for programmers who develop Web applications using the Spring Framework and standard Java EE technologies such as servlets and JSPs: Spring Framework Reference Manuals and Javadoc Java Servlet Technology VMware vfabric tc Server

16 12 Getting Started with tc Server JavaServer Pages (JSP) Technology 12 Overview of tc Server

17 Comparing tc Runtime and Apache Tomcat Comparing tc Runtime and Apache Tomcat The 100-percent compatibility between vfabric tc Server and Apache Tomcat 6 ensures a seamless upgrade path for existing custom-built and commercial software applications already certified for Tomcat. Maintaining this level of compatibility enables customers to add the functionality they need to run and manage their applications more effectively with the least amount of effort. The tc Server runtime component, tc Runtime, also adds many business-critical features to standard Apache Tomcat functionality in the areas of enterprise server configuration, operations and management, diagnostics, and scripting. Subtopics Standard Application Server Features Enterprise Application Server Features Advanced Configuration Features Operations Features Standard Application Server Features tc Runtime and Apache Tomcat share key standard features of application servers. Table 4.1. Standard Application Server Feature Comparison Application Server Features tc Runtime Apache Tomcat Servlet 2.5 support Java Server Pages (JSP) 2.1 support HTTP session clustering Advanced I/O features Pre-built advanced non-blocking I/O components Basic Windows service wrapper Enterprise Application Server Features Because tc Runtime is based on Apache Tomcat 6, it provides a powerful yet lightweight platform that is compatible with existing Tomcat-based applications and with Web applications that run on other Java EE application servers such as IBM WebSphere or Oracle WebLogic. Applications can be seamlessly moved from Apache Tomcat to tc Runtime to gain the benefits that tc Runtime provides beyond the base Apache Tomcat. Table 4.2. Enterprise Application Server Feature Comparison Enterprise Application Server Features tc Runtime Apache Tomcat Multiple runtime instances from a single binary installation No New high-concurrency JDBC connection pool` No Preconfigured for JMX management No Includes latest security vulnerability and bug fixes Rebuild Tomcat yourself to apply incremental fixes. Binary patch updates Binary patches are not provided by Tomcat community. Unix boot scripts No Enhanced Windows service wrapper No VMware vfabric tc Server

18 14 Getting Started with tc Server Advanced Configuration Features tc Runtime has a number of advanced configuration features that Apache Tomcat does not. Table Advanced Configuration Feature Comparison Advanced Configuration Features tc Runtime Apache Tomcat Templated production-ready configuration out-of-the-box. No Create Tomcat single server configuration. No Modify general server configuration including JVM startup parameters. No Modify context container configuration. No Modify server defaults for JSPs and static content. No Add, modify, and delete JDBC datasources. No Modify HTTP and AJP connector settings. No Create and view general services. No Modify general engine configuration. No Pre-tuned JVM options. No Operations Features tc Runtime includes advanced, distributed management and monitoring capabilities through a centralized management console called Hyperic user interface. The tables in this section list the capabilities that tc Runtime provides over and above the base Apache Tomcat and also notes the features that Hyperic provides for existing Apache Tomcat environments. tc Runtime provides a wide range of capabilities that enable developers, administrators, and operators to centrally diagnose, measure, and monitor the distributed application infrastructure. Table 4.4. Diagnostics, Metrics, and Monitoring Feature Comparison Diagnostics, Metrics, and Monitoring Features tc Runtime Apache Tomcat Application deadlock detection No Uncaught exception detection No Garbage collection metrics, including throughput and count No SQL query time monitoring metrics. No Enhance response time monitoring metrics No Enhanced connection pool health metrics No Enhanced thread pool health metrics No Role-based customizable dashboard (via Hyperic) Automated inventory of application servers and software resources (via Hyperic) Real-time metric collection and monitoring of tc Runtime, Tomcat, Apache Web server, Apache ActiveMQ, underlying JVM, operating system, and other resources (via Hyperic) 14 Comparing tc Runtime and Apache Tomcat

19 Comparing tc Runtime and Apache Tomcat 15 Diagnostics, Metrics, and Monitoring Features tc Runtime Apache Tomcat Charting and graphing performance (via Hyperic) Advanced alerting: multi-conditional, availability, event, and recovery alerts, groupbased alerting, and escalation schemes. (via Hyperic) Log file tracing, alerts on event levels (via Hyperic) Alerts based on configuration file updates (via Hyperic) Performance baselining for alert thresholds (via Hyperic) tc Runtime provides a centralized, secure dashboard that enables administrators and operators to organize, operate, and control their distributed applications and infrastructure. Table 4.5. Centralized Operations and Management Feature Comparison Centralized Operations and Management Features tc Runtime Apache Tomcat Secure, distributed, JMX-based server management No Create application server groups (via Hyperic) Application server start/stop/restart from central console (via Hyperic) List deployed applications and current status No Application deploy/undeploy/reload/start/stop No Security and access/authorization control (via Hyperic) Scheduled control: maintenance activities, on-demand actions, scheduled remediation actions, or scheduled responses to alert conditions (via Hyperic) tc Runtime provides scripting support for administrators and operators who prefer to create and run scripts to handle distributed configuration and deployment steps. Table 4.6. Scripting Feature Comparison Scripting Features tc Runtime Apache Tomcat List deployed servers. No Create server groups. No Add and delete servers to and from groups. No List deployed applications, including current status. No Deploy application WAR file. No Undeploy application. No Start, stop, and reload deployed applications. No Get (download) configuration files and JVM parameters from a server. No Modify configuration files on an individual server. No VMware vfabric tc Server

20 16 Getting Started with tc Server Scripting Features tc Runtime Apache Tomcat Set (push) configuration files and JVM parameters to a server group. No Start, stop, and restart a server or group of servers No 16 Comparing tc Runtime and Apache Tomcat

21 Installing vfabric tc Server Installing vfabric tc Server vfabric tc Server has several options for installation and setup. Installation options vary according to the tc Server edition you choose; whether you install tc Server standalone or as part of vfabric Platform installation; and whether your operating system is Linux or another supported platform. Installation also varies according to whether you are installing tc Server for the first time or are upgrading from a previous version. If you have already installed a previous version of tc Server; have created one or more tc Runtime instances; and now want to upgrade all components to the latest version, see Upgrade and Migration Guide. The upgrade guide also describes how to upgrade an existing pre-4.5 Hyperic installation so that it can manage tc Runtime instances. Subtopics Meeting Software System Requirements for tc Server Installing tc Server as Part of vfabric Cloud Application Platform Install tc Server Developer Edition Install tc Server Standard Edition (tc Runtime Only) Install tc Server Standard Edition with Hyperic Management Components Activate a Local vfabric tc Server License Overview of tc Server Directories, Variables, and Configuration Enabling Bash Completion for tc Server Scripts Setting Up Unix Users for tc Server and Hyperic Meeting System Software Requirements for tc Server tc Server requires the Java Development Kit (JDK) or Java Runtime Environment (JRE). Depending on your installation, you might also need to install GNUtar and a database server. Determine whether you must install these components: GNUtar. If you install the compressed TAR file of tc Server in a Unix environment and your tar command does not support the -z option, you must install GNUtar. Database server. If you install tc Server Standard Edition and the platform-neutral version of Hyperic Server and Agent, you must install a database server. It is also recommended that you install a database server for production purposes, if you install the platformneutral or platform-specific version of the Hyperic distribution. The platform-specific versions of the Hyperic distribution bundle a database to get you started, but this database is not recommended for production. For Hyperic Server and Agent requirements, see "Installation Requirements" in vfabric Hyperic Installation Guide. Subtopics Required: Install JDK or JRE Possibly Required: Install a Database Server Possibly Required: Install GNUtar VMware vfabric tc Server

22 18 Getting Started with tc Server Required: Install JDK or JRE All tc Server editions require you to download a JDK or JRE. If you are installing the Hyperic components, the JDK or JRE requirement depends on whether you install a platform-specific version or the platform-neutral version. The platform-neutral version requires a JDK or JRE, and the platform-specific versions bundle one. Prerequisites For platform-specific details of supported and tested JDK or JRE versions, see the tc Server Release Notes on the tc Server Documentation Web site. Go to the appropriate download site for your platform: Java SE Downloads or IBM JDK and JRE Downloads. Procedure 1. On each computer where you plan to install the tc Runtime component of tc Server, download and install a JDK or JRE. 2. If you plan to install the platform-neutral version of the Hyperic components, install a JDK or JRE on each computer on which you will install Hyperic Server or a Hyperic Agent. Each computer requires one JDK or JRE. If you already installed a JDK or JRE on the computer in step 1, you do not need to install another one. 3. Set your JAVA_HOME environment variable to point to your installation and update your PATH environment variable to point to the JAVA_HOME/bin directory. 4. If you are installing the management components of tc Server (Hyperic Server and Hyperic Agent) on a Windows platform, set HQ_JAVA_HOME as a system environment variable that points to the location of your JDK or JRE. Make sure you set HQ_JAVA_HOME as a system environment variable. If you set it as a user environment variable, the Hyperic Agent aborts on startup. Possibly Required: Install a Database Server The Hyperic Server uses a database to store its metadata. The platform-neutral version of Hyperic Server does not, however, bundle a database. If you install tc Server Standard edition and you want to install the platform-neutral version of the Hyperic Server and Agent components, you need to install a database server. It is also recommended that you install a database server for production purposes, if you install the platformneutral or platform-specific version of the Hyperic distribution. The platform-specific versions of the Hyperic distribution bundle a database for you to get started, but this database is not recommended for production. Procedure Follow the procedure in "Set Up Hyperic Database" in vfabric Hyperic Installation Guide. Hyperic Server supports Oracle 10g/11g, PostgreSQL, and MySQL 5.x. Possibly Required: Install GNUtar If you are installing tc Server on Unix and have downloaded the compressed TAR file format (*.tar.gz), the tar command on your computer must be compatible with the tar command required by the tc Server. If the commands are not, compatible, you must install GNUtar. Procedure 1. Open a terminal window and enter: prompt$ tar --help 18 Installing vfabric tc Server

23 Installing vfabric tc Server Search the help output for a -z option, which filters the output through gzip. If the tar command on your computer supports the -z option, then it is compatible with the one required by tc Server and you can begin installing tc Server. If your tar command does not support this option, then you must install GNUtar (gtar) from an external source. Proceed to step Download GNUtar for free from Sunfreeware.com. 4. Update the PATH environment variable (either of the user installing tc Server or the system-wide environment variable) to include the location of the gtar command. The location depends on the directory in which you installed GNUtar. 5. For any references to tar in the tc Server installation procedures, substitute the command gtar. Installing tc Server as Part of vfabric Cloud Application Platform As with previous versions of the product, this version of vfabric tc Server is available as a standalone product installation. Beginning with version 2.6, tc Server is also available as part of vfabric Cloud Application Platform, a set of runtime components that let you build, scale, and run modern, agile applications in virtual environments. If you obtain tc Server standalone, you can install it on both physical and virtual machines according to the procedures in this document. If you obtain tc Server as part of a Standard or Advanced vfabric Platform package, you install it exclusively on VMware virtual machines that run on vsphere. The platform install process adds the vfabric License Server to an existing vcenter server. The vfabric License Server accepts a network license, actually a pool of licenses for vfabric components, which makes it easy to manage the licensing of all components installed on the VMs. If you obtain tc Server as part of vfabric Platform, first complete the license activation and installation procedures in Getting Started with vfabric Cloud Application Platform. Then follow procedures in this document to install tc Server and complete any remaining tc Server-specific installation and configuration tasks. Install tc Server Developer Edition When you install the Developer Edition of tc Server, you create a tc Runtime instance that contains Spring Insight Developer. The procedure covers Unix and Windows installation, although most instructions are specific to Unix. If you install on Windows, change the forward slashes (/) to back slashes (\); other differences in the installation are called out. Prerequisites Verify that your system meets the installation requirements. See Meeting System Software Requirements for tc Server. Review information about tc Server Developer edition and its *.zip or *.tar.gz distribution files. See tc Server Editions. Determine the user that is going to create and run the tc Runtime instances, and create it if necessary. Consider creating a user dedicated to tc Server tasks, putting the user in a separate group from regular users, and disabling its interactive login for security purposes. See Setting Up Unix Users for tc Server and Hyperic. On Unix, never run tc Runtime instances as the root user. For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user. VMware vfabric tc Server

24 20 Getting Started with tc Server Procedure 1. On the VMware Download page, navigate to the tc Server download page and download the Developer Edition distribution in ZIP or compressed TAR file format. vfabric-tc-server-developer-2.6.x.release.zip vfabric-tc-server-developer-2.6.x.release.tar.gz 2. Login to the computer on which you are installing tc Server as the appropriate user, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user. 3. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /opt/ vmware. For example, on Unix: prompt$ mkdir /opt/vmware 4. Extract the tc Server distribution file into the new directory. This action creates a directory called vfabric-tc-server-developer in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on. The templates directory contains a template called insight that contains the Spring Insight application. 5. Create a tc Runtime instance that contains Spring Insight by specifying the insight template. Unix: Change to the /opt/vmware/vfabric-tc-server-developer directory and execute the tcruntimeinstance.sh script to create an instance. VMware recommends that you use the -i option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the tcserver user can write to this directory and that the directory already exists. For example: prompt$ cd /opt/vmware/vfabric-tc-server-developer prompt$./tcruntime-instance.sh create -t insight \ -i /var/opt/vmware/vfabric-tc-server-developer insight-instance Windows: Change to the \opt\vmware\vfabric-tc-server-developer directory and execute the tcruntime-instance.bat script to create an instance: prompt> cd \opt\vmware\vfabric-tc-server-developer prompt> tcruntime-instance.bat create insight-instance -t insight \ -i \var\opt\vmware\vfabric-tc-server-developer 6. Start the new tc Runtime instance. Unix: Execute the tcruntime-ctl.sh script to start the instance; use the -n option to specify the directory in which the instance is located. For example: prompt$./tcruntime-ctl.sh insight-instance start -n /var/opt/vmware/vfabric-tc-server-developer Windows: Execute the tcruntime-ctl.bat script to first install the tc Runtime instance as a Windows service and then start it; for both commands, use the -n option to specify the directory in which the instance is located: prompt> tcruntime-ctl.bat insight-instance install -n \var\opt\vmware\vfabric-tc-server-developer prompt> tcruntime-ctl.bat insight-instance start -n \var\opt\vmware\vfabric-tc-server-developer 20 Installing vfabric tc Server

25 Installing vfabric tc Server 21 On Windows, VMware recommends that you subsequently start and stop the tc Runtime instance through the Windows Services console. The tc Runtime instance is displayed in the console with the name SpringSource tc Runtime - unique-name, where unique-name is a unique combination of server name and servger directory. 7. After the tc Runtime instance starts, invoke Spring Insight in your browser: where host refers to the computer on which Spring Insight is running. If you are on the same computer, you can use localhost: What to do next For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files. For Spring Insight overview information and to create plug-ins that extend Spring Insight, see Spring Insight Developer. Try out the tutorials. See Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances and Tutorial: Very Simple Web Application Development. Install tc Server Standard Edition (tc Runtime Only) When you install tc Server Standard Edition, you can choose to install the tc Runtime component only, without installing any Hyperic components. Prerequisites Verify that your system meets the installation requirements. See Meeting System Software Requirements for tc Server. Review information about tc Server Standard edition and its *.zip or *.tar.gz distribution files. See tc Server Editions. Determine the user that is going to create and run the tc Runtime instances, and create it if necessary. Consider creating a user dedicated to tc Server tasks, putting the user in a separate group from regular users, and disabling its interactive login for security purposes. See Setting Up Unix Users for tc Server and Hyperic. On Unix, never run tc Runtime instances as the root user. For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user. Procedure 1. From the VMware Download page, navigate to the VMware vfabric tc Server download page. 2. Download the Standard Edition Runtime package distribution in ZIP or compressed TAR format to a directory on your computer, for example /home/downloads. vfabric-tc-server-standard-2.6.x.release.zip vfabric-tc-server-standard-2.6.x.release.tar.gz 3. Login to the computer on which you are installing tc Server as the appropriate user, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user. VMware vfabric tc Server

26 22 4. Getting Started with tc Server Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /opt/ vmware. For example, on Unix: prompt$ mkdir /opt/vmware 5. Extract the tc Server distribution file into the new directory. This action installs tc Runtime; there is no installer program. For example, if you created a directory called /opt/vmware in the preceding step, and downloaded the Standard Edition ZIP file in the /home/downloads directory: prompt$ cd /opt/vmware prompt$ unzip /home/downloads/vfabric-tc-server-standard release.zip This action creates a directory called vfabric-tc-server-standard in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on. What to do next If you installed tc Server standalone, activate a local tc Server license as described in Activate a Local vfabric tc Server License. If you installed tc Server as part of vfabric Cloud Application Platform, then you should have already activated a network license using the vsphere client, as described in Installing tc Server as Part of vfabric Cloud Application Platform. For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files For typical post-installation procedures such as creating tc Runtime instances, starting tc Server components, and getting started with the Hyperic user interface, see Post-Installation Tasks. Try out the tutorials. See Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances and Tutorial: Very Simple Web Application Development. Install tc Server Standard Edition and Hyperic Management Components When you install tc Server Standard Edition, you have the option of also installing VMware vfabric Hyperic to monitor and manage tc Server. Hyperic 4.5 and later includes the tc Server Hyperic plug-in, which allows you to use the Hyperic interface to monitor and manage tc Runtime instances. There are two Hyperic components to install. Hyperic Agent is installed on every computer running a tc Runtime instance. Hyperic Agent discovers tc Runtime processes, adds them to the inventory and manages them, through the tc Server plug-in. A computer with tc Server runtime instances and Hyperic Agent is called a "managed node." The other component, Hyperic Server, can be installed on any computer in the network and provides the central control point and user interface to use Hyperic to manage multiple deployments. The procedure breaks the installation steps into those you do on managed node computer(s) and those you do on the Hyperic Server computer. If you are installing everything on the same computer, then simply execute all steps on the same computer. If you are installing tc Runtime instances on multiple computers you must install Hyperic Agent on each computer. Prerequisites Verify that your system meets the installation requirements for installing tc Server with Hyperic management components. See Meeting System Software Requirements for tc Server. 22 Installing vfabric tc Server

27 Installing vfabric tc Server 23 Review information about tc Server Standard edition and it's *.zip or *.tar.gz distribution files. See tc Server Editions. Determine the user that is going to create and run the tc Runtime instances, and create it if necessary. Consider creating a user dedicated to tc Server tasks, putting the user in a separate group from regular users, and disabling its interactive login for security purposes. See Setting Up Unix Users for tc Server and Hyperic for additional information about the Hyperic user. On Unix, never run tc Runtime instances as the root user. For clarity, it is assumed in this topic that you will install and run tc Server and Hyperic Agent as the tcserver user and install and run the Hyperic Server as the hyperic user. If you have an existing Hyperic installation, see Upgrade and Migration Guide for details about upgrading Hyperic with the tc Server Hyperic plug-in. To understand the various installation scenarios for managed nodes and the Hyperic Server, read How tc Server and Hyperic Work Together. Then decide how you will install the components: Install all components on the same computer. Install Hyperic Server on one computer and install the managed node (Hyperic Agent and tc Runtime) on one or more different computers. Procedure 1. On the computer on which you plan to install the managed node (tc Runtime and Hyperic Agent), login as the appropriate user, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su tcserver to become the user. 2. Open a terminal (Unix) or command prompt (Windows) and create two new directories: one to contain the tc Runtime component (such as /opt/vmware/tcserver) and one to contain the Hyperic Agent (such as /opt/vmware/ hyperic.) You can install tc Runtime and Hyperic Agent in the same directory, but in this procedure it is assumed that you install them in different directories. For example, on Unix: prompt$ mkdir /opt/vmware/tcserver prompt$ mkdir /opt/vmware/hyperic 3. From the VMware Download Center, navigate to the VMware vfabric tc Server download page, and download the tc Server Standard edition ZIP or compressed TAR file distribution into a directory on your computer, for example /home/ Downloads: vfabric-tc-server-standard-2.6.x.release.zip vfabric-tc-server-standard-2.6.x.release.tar.gz 4. Extract the tc Server distribution file into the /opt/vmware/tcserver directory. This action installs tc Runtime; there is no installer program. For example, if you created a directory called /opt/vmware/tcserver in the preceding step, and downloaded the Standard Edition file to the /home/downloads directory: prompt$ cd /opt/vmware/tcserver prompt$ unzip /home/downloads/vfabric-tc-server-standard release.zip VMware vfabric tc Server

28 24 Getting Started with tc Server A directory called vfabric-tc-server-standard is created in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on. 5. From the VMware Download Center, navigate to the Hyperic download page. 6. Download the Agent-only 4.6 Hyperic Hyperic EE distribution and unpack it into the /opt/vmware/hyperic directory. The Hyperic Agent is installed in the directory /opt/vmware/hyperic/agent-4.6.x.x-ee. 7. On the computer on which you plan to install Hyperic Server, login as the appropriate user, such as hyperic. 8. Determine whether you need to download and install a JDK/JRE or database server. You need to do this if you are installing the platform-neutral version of Hyperic Server or if you require a production-level installation at this time. The platform-specific version of Hyperic Server bundles a JDK/JRE and a non-production database server to get you started. See Meeting System Software Requirements for tc Server. 9. If you use your own database server, obtain the URL and username/password to connect to it. The installation program for Hyperic Server will ask for database server credentials. 10. If you are installing the managed node (tc Server plus Hyperic Agent) on one or more computers and the Hyperic Server on another computer, open a terminal (Unix) or command prompt (Windows) and create the directory that will contain the Hyperic Server. For example, on Unix: prompt$ mkdir /opt/vmware/hyperic If you are installing all components on the same computer, you can install the Hyperic Server into the Hyperic Agent or tc Runtime directory that you already created (such as /opt/vmware/tcserver in this procedure.) 11. From the VMware Download Center, download the Hyperic EE (Enterprise Edition) distribution and unpack it into a temporary directory. Be sure you download version 4.6 of Hyperic which automatically includes the tc Server Hyperic plug-in. You can download a distribution for your particular platform, such as Windows or Linux, or you can download a platform-neutral distribution that does not contain a JDK or database (labeled nojre.) 12. From your terminal window or command prompt, change to the temporary directory in which you unpacked the Hyperic distribution and execute the setup.sh (Unix) or setup.bat (Windows) script. For example, if you downloaded and unpacked the Hyperic distribution into the /home/downloads directory, your subdirectory is hyperic-hq-installer: prompt$ cd /home/downloads/hyperic-hq-installer prompt$./setup.sh 13. After accepting the terms of agreement, enter 1 to install only the Hyperic Server (you installed the Hyperic Agent in a preceding step.) The script asks a few more questions, such as an encryption key for encrypting the database-user password and the directory in which you will install Hyperic Server (/opt/vmware/hyperic in this procedure.) If you are installing a platformspecific version of Hyperic, the setup.sh script might ask you to run another script as the root user. If you are installing the platform-neutral version of Hyperic, the script asks for information about your database, including the database URL, name and password of the user that connects to the database. When the setup.sh script completes, Hyperic Server is installed in /opt/vmware/hyperic/server-4.6.x.xee. 24 Installing vfabric tc Server

29 Installing vfabric tc Server 25 What to do next If you installed tc Server and Hyperic standalone, activate a local tc Server license as described in Activate a Local vfabric tc Server License. See the vfabric Hyperic Installation Guide for information on installing the local Hyperic license. If you installed tc Server and Hyperic as part of vfabric Cloud Application Platform, then you should have already activated a network license using the vsphere client, as described in Installing tc Server as Part of vfabric Cloud Application Platform. For additional details about the questions asked by the Hyperic Server setup.sh script, see "Installing the Agent and Server from a Tarball or Zip Archive" in vfabric Hyperic Installation Guide. For details about the tc Server directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files. For typical post-installation procedures such as creating tc Runtime instances, starting tc Server components, and getting started with the Hyperic user interface, see Post-Installation Tasks. Try out the tutorials. See Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances and Tutorial: Very Simple Web Application Development. Activate a Local vfabric tc Server License When you purchase a local production vfabric tc Server license, your account manager provides you with one or more serial numbers. This section describes how to activate this local license. This section does not apply if you installed tc Server as part of vfabric Cloud Application Platform; for information on how to activate a network license, see Installing tc Server as Part of vfabric Cloud Application Platform. Procedure 1. On the computer on which you installed tc Server, paste the serial number into a file named vf.tc-serialnumbers.txt. 2. Save this file to the directory appropriate to your operating system: Windows: %ALLUSERSPROFILE%\VMware\vFabric\ Linux: /etc/opt/vmware/vfabric/ 3. Ensure that the file is readable by the user who runs the tc Runtime instance. Overview of tc Server Directories, Variables, and Configuration Files When you install the tc Runtime component, you simply unpack the appropriate *.zip or *.tar.gz file into the main installation directory. This action creates a springsource-tc-server-edition subdirectory, where edition refers to the edition of tc Server that you are using (standard or developer.) This subdirectory in turn contains the following tc Server-related files and directories: tomcat-version. Where version is the version of the core Apache Tomcat on which this version of the tc Runtime is based, such as tomcat a.release. tc Server 2.6 includes both Tomcat 6.0 and Tomcat 7.0. This directory is the basic Apache Tomcat CATALINA_HOME directory. Standard Apache Tomcat users recognize its contents. templates. Out-of-the-box templates for creating customized tc Runtime instances, such as cluster-node enabled or SSLready. You can specify one or more of these templates when you run the tcruntime-instance.sh bat script to create a new tc Runtime instance. VMware vfabric tc Server

30 26 Getting Started with tc Server lib. JAR files that implement the templating mechanism and are used by the tcruntime-instance script. tcruntime-instance.sh bat. Scripts for creating new tc Runtime instances. When you create a new tc Runtime instance with this script, the script by default creates a subdirectory of the springsource-tc-server-edition directory with the same name as the new tc Runtime instance. This new directory is the CATALINA_BASE of the tc Runtime instance. The new directory contains the instance-specific configuration files, its own Web application deployment directory, log files, and so on. tcruntime-ctl.sh bat. Scripts for controlling tc Runtime instances, such as start and stop scripts. The bin directories of individual tc Runtime instances include their own versions of these scripts that in turn call these main scripts. You can also call the top-level scripts if you specify the name of the tc Runtime instance. bash_completion. The bash_completion directory contains scripts to enable the bash completion capabilities for tcruntime-instance.sh and tcruntime-ctl.sh. If you use a bash shell on a Unix-like system and you have the bash-completion package installed, you can use the Tab key to complete command arguments and suggest alternatives when using these tc Server scripts. See Enabling Bash Completion for tc Server Scripts for instructions on setting up this feature. tc Server Variables tc Server uses the following variables: CATALINA_HOME. Root directory of your tc Runtime installation. The CATALINA_HOME variable points to the directory INSTALL_DIR/vfabric-tc-server-edition/ tomcat-version, where INSTALL_DIR is the directory in which you installed tc Server (such as /opt/vmware); edition refers to the edition of tc Server you are using (developer or standard); and version is the version of the underlying Tomcat, such as A.RELEASE. CATALINA_BASE. Root directory of a particular tc Runtime instance. This directory contains the instance-specific files, such as the conf/server.xml file that configures this particular instance. If you created a tc Runtime instance called myserver and you are using the Standard Edition, then the CATALINA_BASE of the instance is INSTALL_DIR/springsource-tc-server-standard/myserver by default. The following variables are "exposed" by tc Runtime, which means that you can set them or use them in your environment (or in the bin/setenv.sh file of your tc Runtime instance) to achieve the specified results: CATALINA_OUT. Unix only. Use this environment variable to specify a file to which a tc Runtime instance writes stdout and stderr messages. If you do not set this environment variable explicitly, the tc Runtime instance writes stdout and stderr messages to the file CATALINA_BASE/logs/catalina.out. For example, to specify that the tc Runtime instance write its stdout and stderr messages to /opt/vmware/tcserver/ tcruntime-instance-6.log, set the variable in your environment or setenv.sh as follows: CATALINA_OUT=/opt/vmware/tcserver/tcruntime-instance-6.log INSTANCE_NAME. Name of the tc Runtime instance. You can use this variable to create other unique variables within configuration scripts. For example, on Unix platforms you can update the bin/setenv.sh file to use the name of the tc Runtime instance when defining the CATALINA_OPTS variable as follows: CATALINA_OPTS="-Dinstance.name=$INSTANCE_NAME" On Windows, the equivalent change would be to the conf/wrapper.conf file as follows: set CATALINA_OPTS=-Dinstance.name=%INSTANCE_NAME% 26 Installing vfabric tc Server

31 Installing vfabric tc Server 27 INSTANCE_BASE. Specifies the parent directory of the tc Runtime instance. The full pathname of the tc Runtime instance directory would be $INSTANCE_BASE/$INSTANCE_NAME. You can use the INSTANCE_BASE variable in the same way as the INSTANCE_NAME variable, as described in the preceding bullet. tc Runtime Instance Directory Structure After you create a new tc Runtime instance, its CATALINA_BASE directory contains the following subdirectories: bin. Contains the tcruntime-ctl.* scripts to start and stop tc Runtime instances, as well as the setenv.* scripts. The *.sh Unix files are functional duplicates of the *.bat Windows files. conf. Contains the configuration files for the tc Runtime instance, such as server.xml, catalina.properties, web.xml, context.xml, and so on. lib. Contains resources shared by all Web applications deployed to the tc Runtime instance. logs. Location of the logs files. webapps. Deployment directory for the Web applications deployed to the tc Runtime instance. work. Temporary work directory for all deployed Web applications. temp. Directory used by the JVM for temporary files. tc Runtime Instance Configuration Files You configure a particular tc Runtime instance by changing its configuration files (either by editing the XML file manually or through the Hyperic user interface). Other topics in this documentation describe how to do this. All the configuration files for a tc Runtime instance are located in its CATALINA_BASE/conf directory. The most important configuration files are as follows: server.xml. Main configuration file for a tc Runtime instance. It configures the behavior of the servlet/jsp container. By default, the server.xml file for a tc Runtime instance uses variable substitution for configuration properties that must be unique across multiple tc Runtime instances on the computer, such as HTTP and JMX port numbers. These variables take the form ${var}. For example, the variable for the HTTP port that the tc Runtime instance listens to is ${http.port}. The specific values for these variables for a particular tc Runtime instance are stored in the catalina.properties file, in the same directory as the server.xml file. catalina.properties. Properties file that contains the tc Runtime instance-specific values for variables in the server.xml file. context.xml. Configures the context that is loaded by all Web applications deployed to the tc Runtime instance. web.xml. Default web.xml file that is loaded by all deployed Web applications, in addition to their individual web.xml files. wrapper.conf. Windows only. Configures the Java Service Wrapper from Tanuki Software used to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user log outs under Windows, service dependencies, and the ability to run services that interact with the desktop. jmxremote.access and jmxremote.password. Configures the JMX users and passwords. logging.properties. Configures the logging system of the tc Runtime instance. Enabling Bash Completion for tc Server Scripts If you use the bash shell on a Unix-like system and you have the bash-completion package installed, you can enable completion support for the tc Server tcruntime-instance.sh and tcruntime-ctl.sh scripts. When enabled, you can VMware vfabric tc Server

32 28 Getting Started with tc Server press the Tab key after entering a few letters of a command argument and either the argument is completed for you or possible alternatives are suggested. Bash completion is enabled by linking the bash completion scripts supplied with tc Server into the bash_completion.d directory on your system. Prerequisites You must be using the bash shell on a Unix-like system and have the bash-completion package installed and enabled. Know the location of the bash_completion.d directory on your system, usually /etc/bash_completion.d. You need superuser access to install the scripts. Either log in as root, or use su or sudo to temporarily become root. Procedure 1. As the superuser, create symbolic links for the tc Server bash completion scripts in the bash_completion.d directory, using a command like the following: prompt# ln -s /opt/vmware/vfabric-tc-server-standard release/bash_completion/* /etc/bash_completion.d Replace /etc/bash_completion.d with the path to the bash_completion.d directory on your system, if it differs. 2. With your regular user login, start a new bash shell or re-source your environment to allow the bash_completion script to recognize the new tc Server scripts. Setting Up Unix Users for tc Server and Hyperic On Unix-like systems, the interaction between Hyperic and tc Server is straightforward as long as tc Runtime instances and the Hyperic Agent run as the same user. You can start, stop, or restart tc Runtime instances and deploy web applications using the Hyperic interface without permission or ownership conflicts, since all processes and commands run as the same user. Beginning with Hyperic release 4.6, the tc Server Hyperic plug-in allows you to run Hyperic Agent and tc Runtime instances with different user IDs. You might do this for increased security, or because the Hyperic Agent needs to run as a privileged user to manage some other resource on the computer, or perhaps you want to run different tc Runtime instances as different users to take advantage of process accounting. The Hyperic 4.6 tc Server plug-in detects the user and group running the tc Server process and records them in parameters in the Hyperic Server resource created for the instance. If the user is different from the user running Hyperic Agent, the plug-in uses su or sudo to set the user whenever you start, restart, or stop a tc Runtime instance or change the tc Runtime instance's configuration through Hyperic. When you deploy a web application through Hyperic, the plug-in ensures that the WAR file ownership and file permissions are set so that the tc Runtime instance can deploy the application. Both Hyperic Agent and tc Runtime instances should ideally run as regular, non-root users. In some cases, you may have to run Hyperic Agent as root in order to monitor or manage resources through Hyperic that cannot be managed with a non-root user. Never, however, run a tc Server instance as root. If you use different non-root users to run tc Server instances and Hyperic Agent, you must create them in the same primary group. This is necessary to allow Hyperic Agent to read files written by the tc Runtime instance. It also enables web application deployments through Hyperic; Hyperic Agent deploys WAR files with group permissions set (640) so that members of the same group can read the WAR. If the Hyperic Agent and tc Runtime instance users are in different groups, tc Runtime will not be able to read the WAR file to deploy it. Subtopics Creating Users and Groups for Hyperic and tc Server Setting the tc Server User in Hyperic 28 Installing vfabric tc Server

33 Installing vfabric tc Server 29 Enabling Hyperic Agent Access to su or sudo Deploying Web Applications on Unix Systems Creating Users and Groups for Hyperic Agent and tc Server When you run Hyperic Agent and tc Runtime instances with different users, they must be in the same primary group to allow them to share files. For better security, you can create a separate group for them. The following procedure shows how to create a group and add users to it for tc Server and Hyperic Agent on Red Hat Linux. The exact commands may be different on other operating systems. Procedure 1. Log in as root and start a terminal session. 2. Use the groupadd command to create a new group. The following example creates a spring group: prompt$ groupadd spring 3. Use the useradd command to create a user for Hyperic Agent in the group you created in the previous step. The following example creates a hyperic user in the spring group: prompt$ useradd hyperic -g spring You can include the -M option to prevent creating a home directory for the user and the -s /sbin/nologin option to prevent anyone from logging in as the hyperic user. Install and run Hyperic Agent as this user. 4. Use the useradd command to create a user to run tc Server instances. The following example creates a tcserver user in the spring group: prompt$ useradd tcserver -g spring You can include the -M option to prevent creating a home directory for the user and the -s /sbin/nologin option to prevent anyone from logging in as the tcserver user. Create the tc Server instance and run it as this user. 5. If you want to run multiple tc Runtime instances under separate user accounts on the same computer, repeat the previous step to create additional tc Server users. Setting the tc Server User in Hyperic Hyperic uses auto-discovery to detect tc Runtime instances. The first time it discovers an instance, it records the user and group running the process. Therefore, the usual method to set the tc Server user is to create the instance and run it as the desired user, allowing Hyperic Agent to discover the instance. If you are migrating to a new Hyperic release and you have existing tc Runtime instances detected by an earlier version of Hyperic, the user and group parameters are blank. The first time auto-discovery runs, the instances will show up as modified in the auto-discovery queue. When you accept the modified resources, the user and group are recorded. If you perform any management operations before these existing instances are auto-discovered, the operation will be performed with the Hyperic Agent user and group. To avoid this, after upgrading Hyperic from a pre-4.6 release, force auto-detection and accept the modified resources before performing any management operations with Hyperic. If you decide to change the tc Server user for an instance previously created with a different user, be sure to chown all the files in the tc Runtime instance directory and ensure they are readable and writable by the new user. Then start the instance as the new user and trigger auto-detect in Hyperic to record the new user in the Hyperic resource record. VMware vfabric tc Server

34 30 Getting Started with tc Server Enabling Hyperic Agent Access to su or sudo Hyperic Agent uses the su or sudo command to execute tasks as the tc Server user. Specifically, if Hyperic Agent is running as root, it uses /bin/su to change to the desired user to perform the task. If running as a non-root user, Hyperic Agent instead uses /bin/sudo to do the work as the tc Server user. There are some prerequisites you must verify to ensure that Hyperic can use su or sudo, described below. If Hyperic Agent is running as root If Hyperic Agent is running as root, it will use su to execute tasks as the tc Server user. You must ensure that /bin/su exists. If not, create a link to it. For example, if su is in /sbin, but not /bin, create a link as follows: prompt$ sudo ln -s /sbin/su /bin/su If Hyperic Agent is running as a non-root user If Hyperic Agent is running as a non-root user, it will use sudo to execute tasks as the tc Server user. You must ensure that / usr/bin/sudo exists and also grant required permissions to the tc Server user in the /etc/sudoers file. For example, if sudo is in /usr/sbin/, but not /bin, create a link as follows: prompt$ sudo ln -s /usr/sbin/sudo /bin/sudo The user running Hyperic Agent needs permission to run the tcruntime-ctl.sh script as the tc Server user without having to enter a password. This is accomplished by editing the /etc/sudoers file as root and adding an entry. For example, if Hyperic Agent is running as user hyperic, tc Server runtime instances are running as user tcserver, and the tcruntimectl.sh script is in /opt/vmware/vfabric-tc-server-standard release/tcruntime-ctl.sh, you would add the following entry to /etc/sudoers: hyperic ALL=(tcserver) NOPASSWD: /opt/vmware/vfabric-tc-server-standard release/tcruntime-ctl.sh Deploying Web Applications on Unix Systems The Hyperic tc Server plug-in ensures that when you deploy a web application, the WAR file ownership and access rights are set so that the tc Runtime instance is able to read the WAR. Depending on the users running Hyperic Agent and the tc Runtime instance, and the method used to deploy the WAR file, there are different scenarios. Cold Deploy When you cold-deploy an application with Hyperic, the Hyperic Agent copies the WAR file into the tc Server instance's webapps/ directory. The WAR file owner and permissions depend on the Hyperic Agent user. If Hyperic Agent is running as root, the WAR file owner and group are set to the user and group stored in the Hyperic resource record for the tc Server instance. The file permissions are set to 600, so only the tc Server instance user has read permission. If the tc Server user and group in the Hyperic resource record are blank, the owner and group are the same as the Hyperic Agent user. If the tc Runtime instance starts as a user other than the Hyperic Agent user, tc Runtime will fail to open the WAR, and the deployment will fail. This could happen after migrating from a pre-4.6 Hyperic release, before the tc Server user is detected and recorded in the Hyperic resource record. If Hyperic Agent is running as a non-root user, the WAR file owner and group are set to the Hyperic Agent user and group, and the file permissions are set to 640 so that members of the same group can read the file. If the tc Runtime user and Hyperic Agent user belong to the same primary group, the application will deploy when the tc Runtime instance starts up. Hot Deploy When you hot-deploy an application with Hyperic, the source WAR file is either uploaded to tc Server via the Hyperic Agent or copied from a file already on the computer. The tc Runtime instance writes the WAR file into its webapps/ directory, so 30 Installing vfabric tc Server

35 Installing vfabric tc Server 31 it creates the file as the user and group currently executing the tc Runtime instance. The file permissions are determined by the umask of that user. This ensures that there should be no file permission conflicts during deployment. VMware vfabric tc Server

36 32 Getting Started with tc Server 32 Installing vfabric tc Server

37 Post-Installation Tasks Post-Installation Tasks After you install the components of vfabric tc Server on all relevant computers, you perform some or all of the following postinstallation tasks, depending on the edition of tc Server: Start and run the Hyperic Server and agents; create and start tc Runtime instances; deploy Web applications to an instance; or invoke and use the Hyperic user interface to monitor and configure tc Runtime instances. (As a performance-monitoring alternative to Hyperic, you can install and configure Spring Insight. See Using Spring Insight.) Creating a New tc Runtime Instance The following sections describe how to create new instances of tc Runtime and provide related information: Creating tc Runtime Instances: Typical Steps tcruntime-instance.sh Reference Pinning tc Runtime Instances to a Specific Version Best Practice: Naming tc Runtime Instances Creating a tc Runtime Instance with a Template Templates Provided by tc Runtime Differences Between the Separate and Combined Layouts The procedural topics cover both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\). Creating tc Runtime Instances: Typical Steps This section describes the simplest way to create a new tc Runtime instance. For an explanation of the type of instance that the example creates, see the description following the procedure. 1. Login to the computer on which you installed tc Server as the user who will run tc Runtime instances, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user. 2. Open a terminal window (Unix) or Command Prompt (Windows). 3. Change to the INSTALL_DIR/vfabric-tc-server-edition-release directory, where INSTALL_DIR refers to the main tc Server installation directory, such as /opt/vmware, edition refers to the edition of tc Server you are using (developer or standard.), and release is the release specifier For example: prompt$ cd /opt/vmware/vfabric-tc-server-standard release 4. Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script, passing it the create servername option. Replace servername with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance. VMWare recommends that you use the -i option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the appropriate user (such as tcserver) can write to this directory and that the directory already exists. For example, on Unix: prompt$./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard myserver On Windows: VMware vfabric tc Server

38 34 Getting Started with tc Server prompt> tcruntime-instance.bat create -i \var\opt\vmware\vfabric-tc-server-standard myserver When the preceding sample command completes, the new tc Runtime instance is located in the /var/opt/vmware/ vfabric-tc-server-standard/myserver directory This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance. By default, the tc Runtime instance uses the JAVA_HOME environment variable for the Java binaries, or the instance uses the java binary that it found in the PATH environment variable when it started. You can specify a specific JAVA_HOME using the --java-home option. The ports of the tc Runtime instance are the default values: HTTP listen port: 8080 JMX port: 6969 AJP port: 8009 Shutdown port: -1 The preceding tcruntime-instance sample did not specify the --version option, so the instance is pinned to the highest tc Runtime version located in the installation directory, for example A.RELEASE. You can use the modify-version verb to unpin the instance. See Pinning tc Runtime Instances to a Specific Version for more information. When you use the tcruntime-instance.sh bat command script to create an instance, you can specify additional optional parameters, as described in tcruntime-instance.sh Reference. For example, you can use the --property option to specify the Unix runtime user for the tc Runtime instance. tcruntime-instance.sh Reference The tcruntime-instance command script has five possible command verbs, used to create, modify, or upgrade a tc Runtime instance, list the existing instances, or display help for the command script. Each command has its own set of options, as described in the tables in this section. Depending on the command, you must specify the name of a tc Runtime instance. The general syntax for each of the commands follows; click on the link to see the options for that particular command: tcruntime-instance tcruntime-instance tcruntime-instance tcruntime-instance tcruntime-instance create [options] instance-name modify-version [options] instance-name upgrade [options] instance-name list [options] help [command-name] The create Command Use the create command to create a new tc Runtime instance. The command requires that you specify a name for the new tc Runtime instance directly after the create verb. When you create a new instance, and you do not specify the --template option to apply one or more specific templates, the tcruntime-instance script creates a basic tc Runtime instance that uses the default template (called bio); this template adds the Blocking IO (BIO) HTTP Connector to the server.xml of the instance. You can use the --template option to apply one or more templates so that the instance is automatically configured for a particular feature, such as the NIO connector, clustering, or SSL. VMWare recommends that you use the -i option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the appropriate user (such as tcserver) can write to this directory and that the directory already exists. Examples of creating new tc Runtime instances are shown after the options reference table. 34 Post-Installation Tasks

39 Post-Installation Tasks 35 The following table lists options for the create command of tcruntime-instance.sh bat. When specifying the most common options, you can use either the short form (such as -i) or the long form (such as --instance-directory); less common options support only the long form. Table 6.1. Options of the create Command Option (Long Form) Option (Short Form, if available) --force N/A Description Forces the script to create a new tc Runtime instance, even if one already exists. By default the script does not force the creation. If you specify this parameter and a tc Runtime instance with the name already exists, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. It is assumed in this case that you do not want to touch the user-specific files, such as Web applications. To update the tc Runtime version used by an instance, use the modify-version command, not the --force option. --help -h Outputs usage information about the create command usage. --interactive N/A Tells the script to interactively ask for configuration properties. For example, use this parameter if you want to change the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps. Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers. --instance-directory instancedir -i instancedir Replace instancedir with the full or relative pathname of the directory in which you want the new tc Runtime instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntimeinstance.sh bat script. The default value of this option is the current working directory. --java-home path_to_jre N/A Hard-codes the directory specified by path_to_jre into various files of the instance, such as the bin/setenv.sh bat file. Replace path_to_jre with the full pathname of the JRE or JDK. If you do not specify this option, then the instance hard-codes the value of the JAVA_HOME global environment variable. VMware vfabric tc Server

40 36 Getting Started with tc Server Option (Long Form) Option (Short Form, if available) --layout layout N/A Description Specifies the type of layout you want your new tc Runtime instance to use: separate or combined. The default value is separate. In the separate layout, CATALINA_HOME and CATALINA_BASE point to different directories; in the combined layout they point to the same directory, which means that the tc Runtime binaries are bundled within your instance. The combined is the standard Apache Tomcat layout. Warning: VMware recommends that you always use the separate layout, which is why it is the default value if you do not specify this option. For addiditonal information, see Differences Between the Separate and Combined Layouts. --properties-file file -f file Specifies the name of a properties file that contains configuration properties that you want to apply to the new tc Runtime instance. When you create the properties file, it should contain one property per line, in the form template-name.property-name=value. The name of the property depends on the template. For example, the default template (called bio) has two configuration properties: http.port and https.port. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the tcruntime-instance script at the command line, rather than the instance taking the default values, create a file such as the following: bio.http.port=9090 bio.https.port=9191 Then point to this configuration property file using this option: --properties-file my-property-file --property templatename.propertyname=value -p templatename.propertyname=value Specifies a single configuration property that you want to apply to the new tc Runtime instance. When you create a tc Runtime instance, the tcruntime-instance script always applies a template, even if it is the default one (called bio). Templates usually have configuration properties. For example, the bio template has 36 Post-Installation Tasks

41 Post-Installation Tasks Option (Long Form) 37 Option (Short Form, if available) Description two configuration properties: http.port and https.port. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the tcruntime-instance script at the command line, rather than the instance taking the default values, use this option to specify the property in the form template-name.propertyname=value. For example, to specify that the HTTP port for a new tc Runtime instance that uses the default template is 9090, specify the property as follows: --property bio.http.port= template template_name -t template_name Applies a template to a newly-created tc Runtime instance. You can specify this option multiple times to apply multiple templates to the instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files that the tcruntime-instance script copies to or merges with 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. Changes to the conf/ server.xml or conf/context.xml files of the instance are contained in template files called conf/server-fragment.xml or conf/context-fragment.xml, respectively. These fragment XML files contain just the additions, deletions, or changes that will be applied to the base tc Runtime instance. When the tcruntime-instance script applies the template after it has created a new base instance, it merges server-fragment.xml or context-fragment.xml files with their base originals, or it might replace other instance files, depending on the contents of the template. For example, the template might copy one or more applications to the webapps directory so that they are automatically deployed on startup. If you use this option to specify one or more templates that do not add a <Connector> element to the server.xml configuration file, the tcruntime-instance script automatically adds a Blocking IO (BIO) HTTP Connector to the instance. If your templates include a VMware vfabric tc Server

42 38 Option (Long Form) Getting Started with tc Server Option (Short Form, if available) Description <Connector> element, then the script does not add a BIO Connector. Replace the template_name argument with the name of an existing subdirectory of the INSTALL_DIR/vfabric-tcserver-edition/templates directory, where edition refers to the Edition of tc Server you are using (developer or standard.) An example of an existing template is apr-ssl or cluster-node. For additional details and examples about using this feature, see Creating a tc Runtime Instance with a Template. The following example shows how be be interactively prompted for configuration properties (such as port numbers) and that you want the new tc Runtime instance to be located in the /var/opt/vmware/vfabric-tc-server-standard directory: prompt$./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard --interactive myserver The following example shows how to pin a new instance to version A.RELEASE of tc Runtime and to specify a hardcoded value for JAVA_HOME: prompt$./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard --version A.RELEASE --java-home /var/opt/java/jdk1.6.0_20 myserver \ The following example shows how to pass the value 9090 to the http.port configuration property of the default template (called bio), rather than use the default value of 8080: prompt$./tcruntime-instance.sh create --property bio.http.port=9090 \ -i /var/opt/vmware/vfabric-tc-server-standard myserver The modify-version Command Use the modify-version command to modify the version of tc Runtime used by an existing instance that is pinned to a particular version of tc Runtime. You cannot use this command to modify an instance so it uses a different major release of tc Runtime, or in other words, from tc Runtime version 6.0.X to 7.0.X. You can use it only to modify the version within a certain major release, such as A to B. Use the --version option to specify the new version of the instance. If you do not specify --version, the resulting instance is unpinned, which means it uses the latest available version of tc Runtime. See Pinning tc Runtime Instances to a Version. Note: It is assumed that you have already installed the tc Runtime version to which you want to modify the existing instance. Examples of modifying existing tc Runtime instances are shown after the options reference table. The following table list options for the modify-version command of tcruntime-instance.sh bat. When specifying the options, you can use either the short form (such as -i) or the long form (such as --instance-directory). Table 6.2. Options of the modify-version Command Option (Long Form) Option (Short Form) Description --version version -v version Pins the instance to the specified version of tc Runtime, such as A.RELEASE. 38 Post-Installation Tasks

43 Post-Installation Tasks Option (Long Form) 39 Option (Short Form) Description Valid values depend on the versions of tc Runtime that you have installed. The tcruntime-instance.sh script determines the list of available versions by searching for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as A.RELEASE. You can check for these directories to determine the versions to which you can pin a tc Runtime instance. If you do not specify this option, the instance is not pinned to a tc Runtime version, which means that when you use the tcruntimectl.sh bat script to start the instance, the script searches for the highest version and applies it to the instance. For example, if A.RELEASE, B.RELEASE and A.RELEASE are all present, and you don't specify this option, then the start script automatically chooses A.RELEASE as the version of the instance. See Pinning a tc Runtime Instance to a Specific Version for more information. --instance-directory instancedir -i instancedir Replace instancedir with the full or relative pathname of the directory that contains the tc Runtime instance you want to modify. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntimeinstance.sh bat script. The default value of this option is the current working directory. --help -h Outputs usage information about the modifyversion command usage. The following example shows how to modify an existing tc Runtime instance called myotherserver to use version A.RELEASE of tc Runtime; the resulting instance will be pinned to this version: prompt$./tcruntime-instance.sh modify-version --version A.RELEASE \ -i /var/opt/vmware/vfabric-tc-server-instances myotherserver In the preceding example, the myotherserver is located in the /var/opt/vmware/vfabric-tc-serverinstances directory. The following example shows how to unpin the myotherserver instance so it always uses the latest available version of tc Runtime when it starts: prompt$./tcruntime-instance.sh modify-version \ -i /var/opt/vmware/vfabric-tc-server-instances myotherserver VMware vfabric tc Server

44 40 Getting Started with tc Server The upgrade Command Use the upgrade command to upgrade an instance to a new version of tc Server. The upgrade command copies the existing instance to a new instance directory and updates the files and descriptors in the instance. The difference between the upgrade command and the modify-version command is that the upgrade command upgrades the tc Server scripts and other tc Server files to a newer version, and the modify-version command changes the tc Runtime version to a tc Runtime based on a different Apache Tomcat release. The upgrade command can upgrade an instance using tc Runtime 6 to a newer version of tc Runtime 6, but not to tc Runtime 7. To move from tc Runtime 6 to tc Runtime 7, create a new instance using tc Runtime 7 and redeploy your Web applications. The usual procedure for using the upgrade command is to: 1. Install the new tc Server release in a directory alongside the existing tc Server installation. 2. Execute the upgrade command from the new tc Server installation directory, specifying the instance to be upgraded in the old tc Server installation directory. This results in a new tc Runtime instance in the new tc Server installation directory. When all instances have been upgraded, restarted, and verified, the old tc Server instance directory can be removed. Before you use the upgrade command: If the instance to be upgraded is running, stop it. For example, execute the following command in the tc Server Installation directory: prompt$ tcruntime-ctl.bat myinstance stop If the instance to be upgraded is installed as a Windows service, uninstall it. For example: prompt$ tcruntime-ctl.bat myinstance uninstall After running the upgrade command, install the new instance as a Windows service (if on Windows) and then start the new instance. If you have linked the CATALINA_HOME/bin/init.d.sh script to /etc/init.d on a UNIX system, unlink the script before upgrading and then re-link the script in the new instance directory after the upgrade is complete. Table 6.3. Options of the upgrade Command Option (Long Form) Option (Short Form) Description --instance-directory instancedir -i instancedir Replace instancedir with the full or relative pathname of the directory where the upgraded instance is to be created. If you specify a relative pathname, the directory is relative to the directory where you run the tcruntimeinstance.sh bat script. The default value of this option is the current working directory. --version version 40 -v version Specifies the tc Runtime version to use for the upgraded instance. This option is required when upgrading an unpinned instance or to prevent the instance from being upgraded to the most recent release. If omitted, the most recent available version of the existing major Post-Installation Tasks

45 Post-Installation Tasks Option (Long Form) 41 Option (Short Form) Description release is used; if the instance is currently using tc Runtime 6, it is upgraded to use the highest tc Runtime 6 version in the tc Server installation directory. Valid values for version depend on the versions of tc Runtime that you have installed. The tcruntime-instance.sh script determines the list of available versions by searching for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as A.RELEASE. You can check for these directories to determine which versions to which you can pin a tc Runtime instance. --help -h Displays usage information for the upgrade command. The following example upgrades the instance at /opt/vmware/vfabric-tc-server-standard/myinstance to a new instance at /opt/vmware/vfabric-tc-server-standard-new/myinstance. The upgraded instance will use tc Runtime release A.RELEASE. The command is executed in the /opt/vmware/vfabric-tc-serverstandard-new directory: prompt$ cd /opt/vmware/vfabric-tc-server-standard-new prompt$./tcruntime-instance.sh upgrade -v A.RELEASE../vfabric-tc-server-standard/myInstance The list Command Use the list command to list the known tc Runtime instances. For each instance, the command outputs the runtime version, its base directory, and its status. The following table lists options for the list command of tcruntime-instance.sh bat. When specifying the options, you can use either the short form (such as -i) or the long form (such as --instance-directory) Table 6.4. Options of the list Command Option (Long Form) Option (Short Form) Description --instance-directory instancedir -i instancedir Replace instancedir with the full or relative pathname of the directory that contains the tc Runtime instances for which you want a listing. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntimeinstance.sh bat script. The default value of this option is the current working directory. --help -h Outputs usage information about the list command usage. The following example shows how to list known instances in the tc Server installation directory. There is one instance, myinstance, in this example. prompt$./tcruntime-instance.sh list -i /var/opt/vmware/vfabric-tc-server-standard Listing instances in '/var/opt/vmware/vfabric-tc-server-standard' myinstance Info: VMware vfabric tc Server

46 42 Getting Started with tc Server Instance name: Runtime version: tc Runtime Base: Status: myinstance A.RELEASE /var/opt/vmware/vfabric-tc-server-standard/myinstance NOT RUNNING Getting Help for tcruntime-instance To view a summary of all available commands of the tcruntime-instance script, use the help command: prompt$./tcruntime-instance.sh help To view the usage information about a particular command, specify the name of the command after the help command: prompt$./tcruntime-instance.sh help create The output includes brief information about the available options. You can also use the --help option of the commands to view the same information: prompt$./tcruntime-instance.sh create -h prompt$./tcruntime-instance.sh create --help Pinning tc Runtime Instances to a Specific Version Depending on whether you explicitly specify the --version parameter of the tcruntime-instance.sh bat script when you create an instance, the resulting tc Runtime instance is either pinned or unpinned to a particular version of tc Runtime. Specifically: If you explicitly specify the --version parameter, the tc Runtime instance is pinned to that version. This means that when you use the tcruntime-ctl.sh bat script to start the instance, the instance always uses this tc Runtime version, even if you have installed a more recent version of the tc Runtime. If you do not specify the --version parameter, the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh bat script to start the instance, the script searches for the most recent version of tc Runtime and applies it to the instance. To determine the list of available versions, search for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as A.RELEASE. For example, if you create a new instance using the following command: prompt$./tcruntime-instance.sh create --version A.RELEASE \ -i /var/opt/vmware/vfabric-tc-server-standard myserver the myserver instance will always use version A.RELEASE of the tc Runtime, even if a more recent version is installed. If, however, you do not specify the --version parameter, for example: prompt$./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard myserver the myserver instance always uses the latest version of tc Runtime that is currently installed. Thus if you later install a new version of tc Runtime (which means that there will be a new tomcat-7.0.x.x-x directory alongside the existing ones), and start the unpinned myserver instance using the tcruntime-ctl.sh bat script, the instance automatically uses the latest tc Runtime version without your having to explicitly do anything. To determine whether an existing tc Runtime instance is pinned, check for the file INSTANCE-DIR/conf/ tomcat.version; if the file exists, then the instance is pinned to the version specified in the file. To change the version of a pinned instance, use the modify-version command together with --version to specify the new version. For example: prompt$./tcruntime-instance.sh modify-version --version A.RELEASE \ -i /var/opt/vmware/vfabric-tc-server-standard myserver 42 Post-Installation Tasks

47 Post-Installation Tasks 43 Finally, if you want to convert a currently pinned instance to one that is unpinned, use the modify-version command without --version. For example: prompt$./tcruntime-instance.sh modify-version -i /var/opt/vmware/vfabric-tc-server-standard myserver Best Practice: Naming tc Runtime Instances The name of a tc Runtime instance is the name of its CATALINA_BASE directory, minus the leading directory paths. As a reminder, CATALINA_BASE is the base directory of the instance; this directory contains the instance-specific startup scripts in the bin sub-directory, the configuration files in the conf sub-directory, and so on. For example, if you create a tc Runtime instance in the /var/opt/vmware/vfabric-tc-server-standard/myserver directory, then its name is myserver. The Hyperic user interface also uses this naming convention when first identifying a tc Runtime instance. In particular, the Hyperic user interface displays an instance with the name platform-resource tc Runtime catalina-base-dir, where platform-resource refers to the computer on which the tc Runtime instance is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames. The Hyperic user interface uses the full pathname of CATALINA_BASE as the default description of the instance. This means, however, that if you create two instances whose full pathnames differ, but their main installation directory names are the same, the instances will show up in the Hyperic user interface with the same names. This makes it difficult to differentiate multiple tc Runtime instances from each other, although you can always look at the description for the full pathname. For this reason, it is best practice to use unique names for the main installation directory for each tc Runtime instance on the same computer. Creating a tc Runtime Instance with a Template Templates make it easier to automatically configure certain tc Runtime features at the time you create a tc Runtime instance. These features include SSL, clustering, and so on. You use the --template option to specify a template to the tcruntime-instance script when you create a new tc Runtime instance. You can specify the --template option multiple times if you want to apply multiple templates, such as clustering and SSL. When you create a tc Runtime instance using tcruntime-instance, the script performs the following high-level steps: Creates the instance directory and applies the base template to it. This template provides configuration common to all tc Runtime instances, such as ensuring that the instance can be monitored with Hyperic. If you specified one or more templates with the --template option, the script applies each template in order. The templates might update the instance's server.xml or context.xml file as well as copy over other files, such as JAR files. Applies any needed configuration properties. The script gets the value of these properties either interactively from you, from the --property or --properties-file options you might have specified at the command-line, or from the default property values if no value is provided. If there are no <Connector> elements in the server.xml file after the templates have been applied, the tcruntimeinstance script adds a Blocking IO (BIO) HTTP Connector to the instance. A template is simply a directory under the INSTALL-DIR/templates directory that contains additional or customized tc Runtime instance files. For example, the directory might contain a conf/server-fragment.xml file, which the tcruntime-instance script uses to update the base server.xml file with the relevant feature. The directory might also contain additional JAR files. An example of creating an instance using the nio-ssl template is as follows: prompt$./tcruntime-instance.sh create --template nio-ssl \ -i /var/opt/vmware/vfabric-tc-server-standard myserver VMware vfabric tc Server

48 44 Getting Started with tc Server In the example, the instance is created in the /var/opt/vmware/vfabric-tc-server-standard directory. To use this feature, the specified template must already exist. You can use one of the out-of-the-box templates. The files that make up a template reside in a single directory; the name of the template directory is the name of the template. The template files are organized in the standard Tomcat subdirectory hierarchy. For example, configuration files live in the conf subdirectory and JAR files live in the lib subdirectory. The configuration files in the conf template directory are actually just fragments of XML, called server-fragment.xml or context-fragment.xml, that contain just the additions, deletions, or changes that the script applies to the base instance. When the tcruntime-instance script applies the template after it has created a new base tc Runtime instance, it merges the XML fragment files with the corresponding base conf/ server.xml or conf/context.xml file, and copies over any other files, such as JAR files. Depending on the contents of the template directory, the new tc Runtime instance might be quite different from the standard one. For example, the template might modify the standard server.xml file with additional server configuration, or copy one or more applications to the webapps directory so that they are automatically deployed on startup. The argument to the --template option must be the tc Runtime template directory. The tcruntime-instance script looks for the template directory in the INSTALL_DIR/vfabric-tc-server-edition-version/templates directory, where edition-versin refers to the edition of tc Server you are using (developer or standard) and the version of tc Server. You can specify the --template option multiple times; the tcruntime-instance script applies each template in the order given. First the script copies over any non-configuration files to the appropriate instance directory, and then the script merges the configuration file fragments with the instance configuration files. You will receive a warning if the creation of the instance copies over files with the same name and directory location from two or more different templates. The following example shows how to create a new tc Runtime instance called myserver using the nio out-of-the-box template which adds a NIO Connector to the server.xml file: prompt$./tcruntime-instance.sh create --template nio -i /var/opt/vmware/vfabric-tc-server-standard myserver In the preceding example, because it does not specify the --version or --java-home options, the instance is unpinned, and thus uses the latest installed version of tc Runtime, and the instance uses the value of JAVA_HOME in the environment. The following example shows how to create an instance that uses two templates: prompt$./tcruntime-instance.sh create --template insight --template jmx-ssl \ -i /var/opt/vmware/vfabric-tc-server-standard myserver Note that the insight template is available only in the Developer Edition of tc Server. Templates Provided by tc Runtime tc Runtime provides a number of out-of-the-box templates. Most are server configuration related; for example, one template sets up a basic cluster node configuration and another sets up SSL. Some templates are provided only in certain editions of tc Server, such as the insight template in the Developer Edition. You can download a tc Server template for setting up HTTP session replication using VMware vfabric GemFire, the in-memory distributed data management platform, from the VMware vfabric GemFire section of the VMware Download Center. For instructions for using the template, see "Setting Up GemFire HTTP Session Management for tc Server" under "Tools and Modules" in the vfabric Gemfire User's Guide. The following example shows how to use the nio out-of-the-box template to create a tc Runtime instance that is automatically configured with the NIO Connector in its server.xml file: prompt$./tcruntime-instance.sh create --template nio -i /var/opt/vmware/vfabric-tc-server-standard myserver-nio Because the nio template is in the templates directory, you simply specify its name at the --template option. The following table lists the templates that are provided by tc Runtime out-of-the-box and how each template differs from the generic tc Runtime instance (created without a specific template.) All templates are located in the INSTALL_DIR/ 44 Post-Installation Tasks

49 Post-Installation Tasks 45 vfabric-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (developer or standard). Table 6.5. Out-of-the-Box Templates Provided by tc Runtime Template Name Comparison with Default tc Runtime Instance base This template is the base from which all new tc Runtime instances are created. It provides the configuration that is common to all tc Runtime instances, such as ensuring that the instance can be monitored with Hyperic. When this template is applied, either the base-tomcat-6 or base-tomcat-7 is applied as well, depending on the tc Runtime version to be used by the instance. base-tomcat-6 Part of the base template, this directory contains files specific to tc Runtime 6. base-tomcat-7 Part of the base template, this directory contains files specific to tc Runtime 7. ajp This template adds an Apache JServe Protocol (AJP) connector, which enables Apache web server to communicate with the tc Runtime instance. For details about the connector, see The AJP Connector in the Apache Tomcat Configuration Reference. apr This template: Adds a APRLifecycleListener to detect the APR-based native library required to use the APR/native connector. Adds the APR HTTPS connector. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Apache Portable Runtime (APR) based Native library for Tomcat on the Apache Tomcat Web site. apr-ssl This template: Adds an APRLifecycleListener to detect the APR-based native library required to use the APR/ native connector. Adds an APR HTTPS connector. Adds a sample certificate and key files for testing the SSL configuration. Warning: These sample certificates and key files are provided only to aid testing and debugging; they are not for production use. You must replace them with your own generated certificates and keys before moving to a production system. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Apache Portable Runtime (APR) based Native library for Tomcat and SSL Configuration HOW-TO on the Apache Tomcat Web site. bio This template adds a Blocking IO (BIO) HTTP Connector to the new instance's server.xml file. bio-ssl This template: Adds a Blocking IO (BIO) HTTPS connector. Adds a sample JKS keystore for testing the SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site. cluster-node This template: Adds the default Cluster configuration at the Engine level. By default, multicast discovery is used to identify other nodes in the cluster. If multicast is not enabled on the subnet or if multiple tc Runtime clusters may be present on the same subnet, reconfigure this cluster node to use static membership. Adds the jvmroute attribute to the Engine element to uniquely identify the node. This is parameterized using ${tcserver.node}, which is defined in the CATALINA_BASE/conf/catalina.properties file. VMware vfabric tc Server

50 46 Template Name Getting Started with tc Server Comparison with Default tc Runtime Instance tc Server provides a default value for the jvmroute attribute. You can specify a value other than the default when you create the tc Runtime instance by specifying the cluster-node.node.name property using the --property option as follows: --property cluster-node.node.name=my-node. Because this template does not specifically add a Connector to the instance's server.xml file, the tcruntime-instance script will automatically add a Blocking IO (BIO) HTTP Connector. For more information, see Clustering/Session Replication HOW-TO on the Apache Tomcat Web site. diagnostics This template: Adds a sample JDBC resource configuration that integrates with the request diagnostics to report slow queries. Adds a ThreadDiagnosticsValve at the Engine level to report on slow running requests. Because this template does not specifically add a Connector to the instance's server.xml file, the tcruntime-instance script will automatically add a Blocking IO (BIO) HTTP Connector. elastic-memory Standard Edition Only. This template is used to create tc Runtime instances running in a vsphere ESX or ESXi VM. It introduces memory management technology into the JVM that allows ESX to more efficiently utilize physical memory resources by reclaiming unused memory from the Java heap. See "Using Elastic Memory for Java" in vfabric tc Server Administration. insight Developer Edition Only. This template adds the Spring Insight Developer Web application to your instance. Spring Insight Developer gives you real-time visibility into the behavior and performance of your applications during the development and testing phase. See Spring Insight Developer. Because this template does not specifically add a Connector to the instance's server.xml file, the tcruntime-instance script will automatically add a Blocking IO (BIO) HTTP Connector. Templates for Spring Insight Operations can be downloaded separately. Spring Insight Operations does for in-production applications what Spring Insight Developer does for application development. It gives you real-time visibility into behavior of deployed applications on one or more production tc Runtime instances. See Spring Insight Operations. jmx-ssl This template: Updates the JmxSocketListener to use SSL for all JMX communication Adds a sample JKS keystore that you can use to test the JMX over SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. Because this template does not specifically add a Connector to the instance's server.xml file, the tcruntime-instance script will automatically add a Blocking IO (BIO) HTTP Connector. For more information, see SSL Configuration HOW-TO on the Apache Tomcat Web site. nio This template adds a Non-Blocking IO (NIO) connector for HTTP. For more information, see The HTTP Connector on the Apache Tomcat Web site. nio-ssl This template: Adds an NIO HTTPS connector. Adds a sample JKS keystore that you can use to test the SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site. Differences Between the Separate and Combined Layouts You can create two flavors of tc Runtime instances, depending on the layout of their files: 46 Post-Installation Tasks

51 Post-Installation Tasks 47 Separate layout: In this layout, the instance's CATALINA_HOME and CATALINA_BASE point to two different directories. Typically, CATALINA_HOME points to a tomcat-6.0.x.x.release directory, which in turn contains the set of tc Runtime binaries that are shared by other instances that use the separate layout. VMware highly recommends you use this layout, which is the default. Combined layout: This layout closely resembles the standard Apache Tomcat layout where the instance's CATALINA_HOME and CATALINA_BASE point to the same directory. This means that each instance that uses the combined layout has its own copy of the tc Runtime binaries. For this reason, it is very difficult to upgrade to a new version of tc Runtime. VMware does not recommend you use this layout, because it is so difficult to upgrade instances. The main reason for using it is if you are familiar with the Apache Tomcat layout and want to continue to use it in your environment. Starting and Stopping tc Runtime Instances The following sections describe how to start and stop tc Runtime instances on both Unix and Windows platforms. On Unix platforms, you typically use shell scripts to start and stop tc Runtime instances; alternatively, you can configure your Unix boot process to start the instance automatically. On Windows, you first install the tc Runtime instance as a Windows Service. You can use the tcruntime-ctl script or the Windows Services console to start and stop it. Unix: Starting and Stopping tc Runtime Instances Interactively Using tcruntime-ctl.sh Unix: Starting tc Runtime Instances Automatically at System Boot Time Windows: Starting and Stopping tc Runtime Instances as Windows Services The Windows Java Service Wrapper tcruntime-ctl Command Reference Windows: Setting the Logon-as-Service Right for a Windows User Unix: Starting and Stopping tc Runtime Instances Interactively Using tcruntime-ctl.sh By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/vfabrictc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as / opt/vmware, and edition refers to the edition or package of tc Server you are using (developer or standard). Each tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance. In the following procedure, it is assumed that you installed a tc Server Standard Edition. To start and stop a tc Runtime instance: 1. Login to the computer on which installed tc Server as the user who will run the tc Runtime instance, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user. 2. Start a terminal window and change to the CATALINA_BASE/bin directory of the tc Runtime instance you want to start or stop. For example, if you installed tc Server in /opt/vmware and created a new tc Runtime instance called myserver in the / var/opt/vmware/vfabric-tc-server-standard directory: prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin 3. Start the tc Runtime instance by executing the tcruntime-ctl.sh start command. For example: prompt$./tcruntime-ctl.sh start This command starts the tc Runtime instance as a daemon under the current user account. VMware vfabric tc Server

52 48 4. Getting Started with tc Server Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop command: prompt$./tcruntime-ctl.sh stop See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script. Unix: Starting tc Runtime Instances Automatically at System Boot Time When you create a tc Runtime instance on a Unix platform, the tcruntime-instance.sh script creates a boot script, instance-name/bin/init.d.sh, which you can install to start the tc Runtime instance automatically at boot time. Once you install the script, whenever the computer reboots, the tc Runtime instance is automatically started. You can also use the script to control the tc Runtime instance the same way you use other scripts in the /etc/init.d directory. About Users and Permissions The scripts in /etc/init.d are owned by root and must be executed by root. When the tc Runtime init.d script executes, it uses /bin/su to execute the tc Runtime instance as another user, tc-server by default. This user account must exist and have permission to read and write all files in the CATALINA_HOME directory. To ensure that file permissions are correct, you should either create the tc Runtime instance while logged in as the user you want to run the instance, or create the instance and then chown the CATALINA_HOME directory and all of its files and subdirectories to the user you want to run the instance. Specify the runtime user on the tcruntime-instance.sh create command line when you create the instance by including --property base.runtime.user=run-time-user in the command, as shown in this example: prompt$./tcruntime-instance.sh create --property base.runtime.user=tcserver \ -i /var/opt/vmware/vfabric-tc-server-standard myinstance Or use the --interactive option, and the tcruntime-instance.sh create command will prompt you to enter the runtime user account. After you create an instance, you can edit the CATALINA_HOME/bin/init.d.sh file and change the value of the TC_RUNTIME_USER variable: TC_RUNTIME_USER="tc-server" Again, ensure that the user exists and owns (or is able to read and write) all files and directories in the CATALINA_HOME directory. Installing the init.d.sh Script To enable the init.d.sh script, you create a link to it in the /etc/init.d directory. Since the scripts in /etc/init.d belong to root, this procedure requires root permission. Do not copy the init.d.sh file into the /etc/init.d directory. The script depends on its location in the bin directory of the tc Runtime instance. Procedure 1. In a Unix terminal window, use the su command to become root, if necessary: prompt$ su Password: Enter the root password at the prompt Install the init.d.sh script in the /etc/init.d directory using a command like the following: Post-Installation Tasks

53 Post-Installation Tasks 49 prompt# ln -s CATALINA_HOME/bin/init.d.sh /etc/init.d/instance-name For example, if you created an instance named MyInstance in the /var/opt/vmware/vfabric-tc-serverstandard directory, enter this command: prompt# ln -s /var/opt/vmware/vfabric-tc-server-standard/myinstance/bin/init.d.sh \ /etc/init.d/myinstance 3. To test the script, restart the computer, or start the tc Runtime instance using the /etc/init.d/instance-name command. For example: prompt# /etc/init.d/myinstance start 4. Check the status of the tc Runtime instance using the /etc/init.d/instance-name status command. For example: prompt# /etc/init.d/myinstance status Using the /etc/init.d Script If you are accustomed to using commands in /etc/init.d to start, stop, and restart services, you can do the same with tc Runtime instances. Internally, the /etc/init.d/instance-name script calls the tcruntime-ctl.sh script in the tc Runtime instance's bin directory, so the options are equivalent. The /etc/init.d/instance-name script supports the commands in the following table: Table 6.6. init.d Commands for tc Runtime Instances Command Description start Starts the Instance stop Shuts down the instance restart Stops and starts the instance status Displays information about the tc Runtime instance and whether it is running or not running. You must be root when you execute the command. For example, to restart a tc Runtime instance named MyInstance: prompt$ sudo /etc/init.d/myinstance restart Windows: Starting and Stopping tc Runtime Instances as Windows Services By default, the tcruntime-instance.bat script creates all tc Runtime instances under the INSTALL_DIR\vfabrictc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as \opt \vmware and edition is developer or standard. Each particular tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance. If so, adjust the following procedure accordingly. In the following procedure, it is assumed that you installed a tc Server Standard Edition. To start and stop tc Runtime instances as Windows Services: 1. Login to the computer on which you installed tc Server as the userwho will run the tc Runtime instance, such as tcserver. 2. If this is the first time that you will install and start the tc Runtime instance after creating it, start a Command Prompt window and continue with this procedure. If you have already installed the tc Runtime instance as a Windows Service, use the Windows Services control panel to start and stop it. VMware vfabric tc Server

54 50 3. Getting Started with tc Server Change to the CATALINA_BASE\bin directory of the tc Runtime instance you want to start or stop. For example, if you installed tc Server in \opt\vmware and created a new tc Runtime instance called myserver in the \var\opt\vmware\vfabric-tc-server-standard directory: prompt> cd \var\opt\vmware\vfabric-tc-server-standard\myserver\bin 4. Install the tc Runtime instance as a Windows service: prompt> tcruntime-ctl.bat install The command installs the tc Runtime instance as an automatic Windows Service, which means that the tc Runtime instance starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel. You should see a message indicating a successful installation: wrapper SpringSource tc Runtime - tcserver-c-var-opt-vmware-vfabric-tc-serverstandard-myserver installed. 5. Start and stop the tc Runtime instance using the tcruntime-ctl.bat script or the Windows Services console. The tc Runtime instance is displayed in the console with the name SpringSource tc Runtime - unique-name, where uniquename is a unique combination of server name and server directory. To start an instance using tcruntime-ctl.bat: prompt> tcruntime-ctl.bat start To stop an instance using tc-runtime-ctl.bat: prompt> tcruntime-ctl.bat stop To uninstall the tc Runtime service, execute the following command: prompt> tcruntime-ctl.bat uninstall Although VMware recommends that you always install the tc Runtime instance as a Windows service and stop and start it using the Services console, you can also stop and start the tc Runtime instance manually. See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script. Windows Java Service Wrapper On Windows, tc Runtime uses a Java Service Wrapper from Tanuki Software to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user logouts under Windows, service dependencies, and the ability to run services which interact with the desktop. The wrapper is configured using the CATALINA_BASE\conf\wrapper.conf file, where CATALINA_BASE is the toplevel directory of the tc Runtime instance, such as \var\opt\vmware\vfabric-tc-server-standard\myserver. In most circumstances, you do not need to update this file because the default one created when you created the tc Runtime instance handles most use cases. However, you might sometimes want to further customize the Windows service to fit particular circumstances of your environment; in which case you can edit the wrapper.conf file. For details about the configuration properties, see Configuration Property Overview. tcruntime-ctl Command Reference You use the tcruntime-ctl.sh (Unix) and tcruntime-ctl.bat (Windows) command scripts to manage tc Runtime instances. The syntax of the script is as follows: tcruntime-ctl.sh bat command [option] 50 Post-Installation Tasks

55 Post-Installation Tasks 51 Typically, you run the command from the bin directory of the tc Runtime instance itself. However, you can also run it from the INSTALL_DIR/vfabric-tc-server-edition directory if you specify the name of the instance, where INSTALL_DIR refers to the directory in which you installed tc Server and edition refers the edition of tc Server (developer or standard.) For example, to start a tc Runtime instance called myserver from the bin directory of the instance itself on Unix: prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin prompt$./tcruntime-ctl.sh start You can accomplish the same thing by running the command from the main installation directory by specifying the name of the instance and its location with the -n option: prompt$ cd /opt/vmware/vfabric-tc-server-standard prompt$./tcruntime-ctl.sh myserver start -n /var/opt/vmware/vfabric-tc-server-standard It is assumed in the remainder of this section that you are running the command script from the bin directory of the tc Runtime instance. The following table describes the tcruntime-ctl script commands and supported platforms. Table 6.7. Commands of the tcruntime-ctl Script Command Description Platform install run-as-user Installs the tc Runtime instance as a Windows service. You then start and stop the service using the Windows Service console. Windows only The optional run-as-user parameter specifies the user account that you want the tc Runtime service to actually run as when you start the service using the Windows Service console; if you do not specify this parameter, then the user account that initially installed it is used. You can specify only user accounts that have their Logon as Service right set to run a Windows service. See Setting the Logon-As- Service Right for a Windows User. When you run this command and explicitly specify a run-as-user user, the script asks you for the password of the specified user. tc Runtime still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it fails with a logon error. You must uninstall the service and reinstall it with the correct password. uninstall Uninstalls the tc Runtime instance from the Windows Service. Windows only start Starts the tc Runtime instance as a daemon process. Unix and Windows On Windows, you must have previously installed the tc Runtime instance as a Windows service to be able to start it using the tcruntime-ctl.bat start command; see the documentation on the tcruntime-ctl.bat install command in this table for more information. restart timeout Stops, and then immediately starts, a running tc Runtime instance. As with the start command, restart starts the instance as a daemon process. Unix and Windows On Windows, you must have previously installed the tc Runtime instance as a Windows service to be able to restart it using the tcruntime-ctl.bat restart command; see the documentation on the tcruntime-ctl.bat install command in this table for more information. By default, the tcruntime-ctl script (when stopping the tc Runtime instance) waits for up to 60 seconds for the process to exit gracefully. If the server process exits earlier, the script proceeds to restart the server. If the process has not exited by the end of the timeout period, the script forces a termination of the process before restarting the server. Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds: prompt$./tcruntime-ctl.sh restart 10 VMware vfabric tc Server

56 52 Getting Started with tc Server Command Description Platform run Starts the tc Runtime instance as a foreground process. Unix and Windows batch Runs the tc Runtime instance using the catalina.bat script as a batch job. Specifically, the script starts the tc Runtime instance by running the following command: %CATALINA_HOME%\bin\catalina.bat run. Windows only stop timeout Stops a running tc Runtime instance. By default, the tcruntime-ctl script waits for up to 60 seconds for the process to exit gracefully; if it has not, then the script forces a termination of the process. Unix and Windows Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds: prompt$./tcruntime-ctl.sh stop 10 status Reports the status of a tc Runtime instance, such as whether it is running or stopped, as well as useful information such as the directory from which the tc Runtime instance gets its binary files, the main instance source directory, and so on. Unix and Windows The following table describes the options you can use with the tcruntime-ctl script. All the options are optional; you can use them with any of the tcruntime-ctl commands. Table 6.8. Options of the tcruntime-ctl Script Option Description -d tcruntimedir Replace tcruntimedir with the full pathname of the tc Server installation directory. Use this option if you are running the tcruntime-ctl.sh bat script from a location other than its default location. The default value of this option is the location of the tcruntime-ctl.sh bat script. -n instancedir Replace instancedir with the full pathname of the parent of the tc Runtime instance directory. Use this option if the tc Runtime instance directory is not in the default location (i.e., the main tc Server installation directory). For example, if the full instance directory of a tc Runtime instance is /var/opt/vmware/ vfabric-tc-server-standard/myserver, then you would specify /var/opt/vmware/ vfabric-tc-server-standard for this option. The default value of this option is the current working directory. The following example shows how to stop the tc Runtime instance called myserver, located in the /var/opt/vmware/ vfabric-tc-server-standard directory, after waiting for up to 60 seconds: prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin prompt$./tcruntime-ctl.sh stop 60 In the following example, use of the -n option indicates that the tc Runtime instance called myotherinstance has an instance directory of /var/opt/vmware/vfabric-tc-server-standard/myotherinstance. The example shows how to use the tcruntime-ctl script located in the main tc Server installation directory. prompt$ cd /opt/vmware/vfabric-tc-server-standard prompt$./tcruntime-ctl.sh myotherinstance stop 60 -n /var/opt/vmware/vfabric-tc-server-standard Windows: Setting the Logon-as-Service Right for a Windows User The tcruntime-ctl.bat install command has an optional run-as-user parameter by which you specify the user account that you want the tc Runtime service to run as when you start the service from the Windows Service console. Windows requires that the specified user account must have their Logon as Service right set for this feature to work properly. To set this right: 52 Post-Installation Tasks

57 Post-Installation Tasks 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. 53 The Local Security Policy tool does not appear to be available on Home versions of Windows 2000 and XP. It is thus not possible to run the tc Runtime service as a specific account under those versions of Windows. Windows: Installing the Hyperic Server and Agents as Windows Services VMware recommends that you install both the Hyperic Server and all Hyperic Agents as Windows Services, and then start and stop them from the Service console. This section describes how to install both components. See Starting and Stopping the Hyperic Server and Agents for details about starting and stopping the Hyperic Server and Agents, particularly when starting the Hyperic Agent for the first time. To install the Hyperic Server as a Windows Service: 1. Login to the computer on which you installed Hyperic as the appropriate user, such as hyperic. 2. Open a Command Prompt window. 3. Change to the HQ_SERVER_INSTALL_DIR\bin directory, where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the Hyperic Server, such as \opt\vmware\hyperic\server-4.6.x.x-ee\bin: prompt> cd \opt\vmware\hyperic\server-4.6.x.x-ee\bin 4. To install the Hyperic Server as a Windows Service: prompt> hq-server.exe -i After a few status messages, you will see a Done. message when installation is complete. The command installs the Hyperic Server as an automatic Windows Service, which means that the server starts automatically when you start the Windows computer. You can change this behavior through the Windows Service control panel. Now, and subsequently, start (and stop) the Hyperic Server using the Windows Service control panel. The Hyperic Server is listed as Hyperic HQ Server. 5. To uninstall the Windows service: prompt> hq-server.exe -u You will see a Removing 'Hyperic HQ Server' Service... Done upon completion. To install the Hyperic Agent as a Windows Service: 1. Login to the computer on which you installed Hyperic as the appropriate user, such as hyperic. 2. Start a Command Prompt window. VMware vfabric tc Server

58 54 Getting Started with tc Server 3. If you have not already done so, set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Set it as a system environment variable; if you set it as a user environment variable, the Hyperic Agent aborts on startup. 4. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the Hyperic Agent, such as \opt\vmware\hyperic\hyperic\agent-4.6.x.x-ee\bin: prompt> cd \opt\vmware\hyperic\agent-4.6.x.x-ee\bin 5. To install the Hyperic Agent as a Windows service: prompt> hq-agent.bat install You see a Hyperic HQ Agent installed. message upon completion. The preceding command installs the Hyperic Agent as an automatic Windows Service, which means that the agent starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel. If you are starting the Hyperic Agent for the first time, see the procedure for starting the Hyperic Agents for further instructions. Subsequently, start (and stop) the Hyperic Agent using the Windows Service control panel. The Hyperic Server is listed as Hyperic HQ Server. 6. To remove (uninstall) the Windows service: prompt> hq-agent.bat remove You will see a Hyperic HQ Agent removed. message upon completion. Starting and Stopping the Hyperic Server and Agents This section describes how to control the Hyperic Server and Agents, specifically starting and stopping them. On Unix platforms, you always use shell scripts to start and stop the Hyperic Server and Hyperic Agent. On Windows, it is recommended that you first install both the server and agents as Windows Services, and subsequently use the Windows Services console to start and stop them. Using the Windows Services console, you can also specify whether the Hyperic Server and Agent should start automatically when the operating system itself starts. The section below describes how to install the server and agents as Windows services. Depending on how you have configured all the components of tc Server (tc Runtime, Hyperic Server and Hyperic Agents), you might run the commands to start and stop the Hyperic Agent and Server on the same computer or on different computers. This section provides basic information about starting and stopping the Hyperic Server and Agent, just enough to get you up and running. For additional detailed information, see "Configure and Run the Hyperic Server" and "Configure and Run the Hyperic Agent" in vfabric Hyperic Installation and Configuration. Unix: Starting and Stopping the Hyperic Server and Agent To start and stop the Hyperic Server: 1. Login to the computer on which you installed Hyperic Server as the appropriate user, such as hyperic. On Unix, if you have disabled interactive login, login as the root user and use su - hyperic to become the user. 2. Open a new terminal window. 3. Change to the HQ_SERVER_INSTALL_DIR/bin directory, where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the Hyperic Server, such as /opt/vmware/hyperic/server-4.6.x.x-ee. For example: prompt$ cd /opt/vmware/hyperic/server-4.6.x.x-ee/bin 54 Post-Installation Tasks

59 Post-Installation Tasks To start the Hyperic Server: prompt$./hq-server.sh start The script displays Starting HQ Server... and then the shell/command Prompt on success. 5. To stop the Hyperic Server: prompt$./hq-server.sh stop The server is fully stopped when you see the message Stopped HQ Server. See the HQ_SERVER_INSTALL_DIR/logs/server.log for details about the starting or stopping of the Hyperic Server. To start and stop the Hyperic Agent: 1. Login to the computer on which you installed Hyperic Agent as the appropriate user, such as hyperic. On Unix, if you have disabled interactive login, login as the root user and use su - hyperic to become the user. 2. Start a new terminal window. 3. Change to the HQ_AGENT_INSTALL_DIR/bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the Hyperic Agent, such as /opt/vmware/hyperic/agent-4.6.x.x-ee. For example: prompt$ cd /opt/vmware/hyperic/agent-4.6.x.x-ee/bin 4. To start the Hyperic Agent, execute the following command: prompt$./hq-agent.sh start The script displays Starting HQ Agent... and then the shell/command Prompt on success. The first time you start the agent, the script requests information about the Hyperic Server to which it will communicate; this is a one-time event and subsequent starts of the agent do not require this input. For more information about these prompts, see the table in "Configure Agent - Server Communication Interactively" under "Configure and Run the Hyperic Agent" in vfabric Hyperic Installation Guide. 5. To stop the Hyperic Agent, execute the following command: prompt$./hq-agent.sh stop The agent is fully stopped when you see the message Stopped HQ Agent. See the HQ_AGENT_INSTALL_DIR/log/agent.log for details about the starting or stopping of the Hyperic Agent. Windows: Starting and Stopping the Hyperic Server and Agent To start and stop the Hyperic Server: 1. If you have not already done so, install the Hyperic Server as a Windows Service, as described in Installing the Hyperic Server and Agents as Windows Services. 2. Start (and stop) the Hyperic Server using the Windows Service control panel. The Hyperic Server is listed as Hyperic HQ Server. See the HQ_SERVER_INSTALL_DIR\logs\server.log for details about the starting or stopping of the Hyperic Server. To start and stop the Hyperic Agent: 1. If you have not already done so, install the Hyperic Agent as a Windows Service, as described in Installing the Hyperic Server and Agents as Windows Services. VMware vfabric tc Server

60 56 2. Getting Started with tc Server If this is the first time you start the Hyperic Agent after installing it, start a Command Prompt window and continue with this procedure. Otherwise, use the Windows Service console to start (and stop) the Hyperic Agent. The Hyperic Agent is listed as the Hyperic HQ Agent. 3. If you have not already done so, set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Note that you are required to set it as a system environment variable; if you set it as a user environment variable, the Hyperic Agent will abort on startup. 4. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the Hyperic Agent, for example \opt\vmware\hyperic\agent-4.6.x.x-ee. For example: prompt> cd \opt\vmware\hyperic\agent-4.6.x.x-ee\bin 5. The first time you start the Hyperic Agent, you must start it from the command line: prompt> hq-agent.bat start The command requests information about the Hyperic Server to which it will communicate; this is a one-time event and subsequent starts of the Hyperic Agent do not require this input. For more information about these prompts, see the table in "Configure Agent - Server Communication Interactively" under "Configure and Run the Hyperic Agent" in vfabric Hyperic Installation Guide. 6. Subsequently, start (and stop) the Hyperic Agent using the Windows Service console. The Hyperic Agent is listed as the Hyperic HQ Agent. See the HQ_AGENT_INSTALL_DIR\log\agent.log for details about the starting or stopping of the Hyperic Agent. Getting Started with the Hyperic User Interface After you install and start the Hyperic Server and all the agents on all computers that host tc Runtime instances, you invoke the Hyperic user interface in your browser so that you can start using it to monitor and configure tc Runtime instances, as well as other resources. The following procedure describes how to access the Hyperic user interface, add a tc Runtime instance to the Hyperic inventory, and update the tc Runtime instance JMX configuration properties so that Hyperic can manage them. 1. Invoke the Hyperic user interface in your browser: where: host is the computer on which you installed the Hyperic Server. If your browser is running on the same computer as the Hyperic Server, you can use localhost or port is the TCP/IP listen port of the Hyperic Server, specified when you installed the server. The default value is The TCP/IP listen port is configured in the HQ_SERVER/conf/hq-server.conf file, where HQ_SERVER is the directory in which you installed the Hyperic Server. If the default listen port does not work, search this file for the actual value of the server.webapp.port property. For example, use the following URL if Hyperic server is running locally using the default listen port: At the login screen, enter the administrator login. The default username is hqadmin, with password hqadmin. Post-Installation Tasks

61 Post-Installation Tasks 57 The server administrator username and password are configured in the HQ_SERVER/data/hq-serverinstall.conf file, where HQ_SERVER is the directory in which you installed the Hyperic 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 Hyperic user interface, not its functionality. VMware recommends you select hqadmin then click OK. You can change the default dashboard after you log in. 4. The following graphic displays the main Hyperic dashboard. Highlighted objects are ones that you always use or use when you get started; see the explanation for each object after the graphic. VMware vfabric tc Server

62 58 Getting Started with tc Server 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 Hyperic, quickly scan the resources that are currently down, or easily go to the resources you have most recently viewed. The Auto-Discovery Portlet shows resources that Hyperic has auto-discovered but you have not yet worked with (either adding them to the Hyperic inventory or skipping them). For example, if you start a tc Runtime instance before logging into Hyperic, then the instance automatically shows up in the auto-discovery portlet. In the next step you will add these resources to Hyperic's inventory. The Hyperic UI itself uses a tc Runtime internally called hq-server, which is also listed in the Auto-Discovery portlet. 58 Post-Installation Tasks

63 Post-Installation Tasks 59 The Help button provides context-sensitive online help, with useful information about what tasks you can perform on each Hyperic user interface page. 5. Import your operating system platform, the tc Runtime instance, and other resources running on the platform into the Hyperic inventory by selecting the appropriate radio buttons next to the resource in the Auto-Discovery portlet and clicking Add to Inventory, as shown in the following graphic. The tc Runtime instance shows up as platform-resource tc Runtime catalina-base-dir in the Hyperic user interface, where platform-resource refers to the computer on which the instance is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames. For example: my-desktop tc Runtime myserver. The Hyperic Agent might also show up in the auto-discovery portlet, listed as HQ Agent 4.6.X.X-EE. Because of the auto-discovery feature of Hyperic, your operating system platform should automatically show up in the Auto-Discovery portlet on the main Dashboard screen of the Hyperic user interface. Other resources running on the operating system, such as other tc Runtime instances, will also show up in the portlet. This is true for all computers running Hyperic agents that communicate with this Hyperic Server. It can sometimes take a few minutes for a newly-started resource, such as the tc Runtime instance, to show up in the auto-discovery portlet. VMware vfabric tc Server

64 60 Getting Started with tc Server After you click Add to Inventory, selected resources show up in the Recently Added portlet of the main Dashboard. 6. Click the Resources > Browse link at the top of the Hyperic user interface. This brings you to a console page from which you can view all the resources in the Hyperic inventory. You view the tc Runtime instances by clicking on the Servers (X) link, as shown: 60 Post-Installation Tasks

65 Post-Installation Tasks Click the Servers (X) link. A list of all the servers in your inventory appears in the table. The tc Runtime instances are listed as platform-resource tc Runtime catalina-base-dir. 8. In the table, click on the tc Runtime instance you just added to the Hyperic inventory, as shown in the preceding graphic. Hyperic displays the configuration and management pages of a tc Runtime instance, as shown in the next graphic and ensuing explanation. VMware vfabric tc Server

66 62 Getting Started with tc Server Monitor tab. Displays monitoring information about a tc Runtime instance and its services, such as the deadlocks detected, available heap memory, and so on. The charts show either graphical or tabular data about the metrics; click Indicators or Metric Data to view each kind of data. Click a particular service in the Services table to view diagnostic information about that particular service that is associated with the tc Runtime instance. Inventory tab. View and manage the tc Runtime instance's general properties, the services hosted by the server, groups containing the server, and the server's monitoring and control configuration. Alert tab. View, configure, and create alerts for a tc Runtime instance. Control tab. Start, stop, and restart this tc Runtime instance, as well as schedule one of these actions for a future date. 62 Post-Installation Tasks

67 Post-Installation Tasks 63 Views tab. Has two subtabs: Server Configuration and Application Management. Use the Server Configuration tab to configure the tc Runtime instance, such as startup JVM parameters, JSP behavior, and properties of the Catalina service, such as connectors and engines. The application deployment tab allows you to deploy Web applications to the tc Runtime instance, as well as start, stop, reload, and undeploy already deployed Web applications. 9. Click the Inventory tab. 10. Scroll down to the Configuration Properties section. The Hyperic user interface uses the values of the fields in this section to connect to the tc Runtime instance, control it, and so on. In particular, the Shared section specifies the JMX properties of the tc Runtime instance; Hyperic uses JMX to configure and manage tc Runtime instances. If you have not changed the JMX values in server.xml, Hyperic will populate these fields automatically, so the tc Runtime instance should work with Hyperic without change. However, if you have changed the JMX values of your tc Runtime instance by manually updating its server.xml file, then you must change the corresponding fields in the Hyperic user interface, as described in the following procedure. a. Click Edit. b. Update the following fields as required: jmx.url: URL that the Hyperic user interface uses to connect to the JMX server associated with the tc Runtime instance. The format is service:jmx:rmi:///jndi/rmi://host:jmxport/jmxrmi. Be sure the value of host is the name of the computer on which the JMX server is running (you can use localhost if it is the same as the computer hosting Hyperic server) and that the value of jmxport is the value of the port VMware vfabric tc Server

68 64 Getting Started with tc Server attribute of the <Listener> element in the tc Runtime instance's server.xml file that corresponds to the com.springsource.tcserver.serviceability.rmi.jmxsocketlistener class (default value is 6969). jmx.username: JMX username that Hyperic uses to connect to the JMX server associated with the tc Runtime instance. The username is stored in the file pointed to by the passwordfile attribute of the <Listener> element in the tc Runtime instance's server.xml file that corresponds to the com.springsource.tcserver.serviceability.rmi.jmxsocketlistener class; by default, the name of this file is CATALINA_BASE/conf/jmxremote.password. The default username is admin. jmx.password: Password of jmx.username. The password is stored in the same file as the username, as described in the preceding bullet. The default password is springsource. c. Click OK. You are now ready to monitor and configure the tc Runtime instance using Hyperic. For a tutorial that describes how to perform common management and configuration tasks using Hyperic, see Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances. For detailed conceptual and task information about using Hyperic, click the Help button on the Hyperic user interface or consult the vfabric Hyperic documentation. Deploying Applications to tc Runtime Instances Deployment refers to the process of installing a Web application into the tc Runtime instance. This section describes two ways to deploy Web applications to the tc Runtime instance. Static deployment: To deploy statically, you simply copy your Web application, either as a packaged WAR file or as an uncompressed directory (also called exploded), to the deployment directory of the tc Runtime instance. This directory is specified by the appbase property of your virtual host; the default value is CATALINA_BASE/webapps. Assuming that the autodeploy property of your host is enabled (default value), then as soon as you copy your Web application to the deployment directory, the tc Runtime instance deploys and starts it, and users can immediately start using the application. See the procedure below for details. Dynamic deployment using Hyperic: The Hyperic user interface is a sophisticated GUI console with which you can deploy Web applications located on local or remote computers. You can also create groups of tc Runtime instances and then deploy a WAR file to the group; the Hyperic user interface then takes care of deploying the WAR file to each individual member of the group. This feature helps you avoid having to deploy to each tc Runtime instance individually, saving you much time if you have many servers in your environment. See Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances for a tutorial that describes how to deploy applications to single tc Runtime instances, create tc Runtime groups, and deploy an application to the group. It is assumed in this section that you have already created a Web application and want to deploy it to a tc Runtime instance so you can start using the application. If you do not have a Web application, see Tutorial: Very Simple Web Application Development for a tutorial that describes how to create a very simple HelloWorld application. To deploy a Web application statically: Copy the WAR or exploded directory to the deployment directory, which by default is CATALINA_BASE/webapps. For example, if your CATALINA_BASE variable is /var/opt/vmware/vfabric-tcserver-standard/myserver, and your Web application is the exploded directory /var/apps/myapp, then you deploy it statically with the following command: prompt$ cp /var/apps/myapp /var/opt/vmware/vfabric-tc-server-standard/myserver/webapps If you want to use a different deployment directory than the default CATALINA_BASE/webapps, set the appbase attribute of the <Host> element that configures the virtual host for your tc Runtime instance. For additional details about static deployment, see Tomcat Web Application Deployment. 64 Post-Installation Tasks

69 Post-Installation Tasks 65 Deploying Applications Using Tomcat Manager (Developer Edition Only) The tc Server Developer Edition includes Tomcat Manager, an Apache Web application that you can use to deploy your own Web applications and manage their lifecycle, such as starting, stopping, and undeploying them. The default tc Server Developer Edition configuration does not automatically authorize any user to access Tomcat Manager, so you must configure a role and a user before you can use Tomcat Manager. The Tomcat Manager web application is updated in Tomcat 7.0 with separate roles to secure access to the application from different paths. To use a Web browser to deploy Web applications, you need the manager-gui role for tc Runtime 7. Refer to the Apache Web site for complete documentation for Tomcat Manager. The following procedure describes how to authorize a user to access Tomcat Manager, and then how to invoke the Web application in your browser. Procedure 1. Update the CATALINA_BASE/conf/tomcat-users.xml file in the tc Runtime instance by adding a manager role (tc Runtime 6.0) or manager-gui role (tc Runtime 7.0). An entry for the manager role for tc Runtime 6.0 looks like this: <tomcat-users> <role rolename="manager" />... </tomcat-users> An entry for the manager-gui role for tc Runtime 7.0 looks like this: <tomcat-users> <role rolename="manager-gui" />... </tomcat-users> 2. In the same file, add a user with the manager or manager-gui role, depending on your tc Runtime version. The user element for user tomcat with password tomcat in a tc Runtime 6 tomcat-users.xml looks like this: <tomcat-users> <role rolename="manager" /> <user username="tomcat" password="tomcat" roles="manager" /> </tomcat-users> The user element for tc Runtime 7 looks like the following: <tomcat-users> <role rolename="manager-gui" /> <user username="tomcat" password="tomcat" roles="manager-gui" /> </tomcat-users> 3. Restart the tc Runtime instance for the changes to take effect. 4. Invoke Tomcat Manager in your browser using the following URL: where host refers to the computer running the tc Runtime instance. 5. Enter the user and password you configured in the tomcat-users.xml file. The Applications table lists the currently deployed applications. Click the links in the Path column to actually invoke each application. The Commands column includes buttons for starting, stopping, reloading, and undeploying the applications. VMware vfabric tc Server

70 66 Getting Started with tc Server From the Deploy section, you can deploy Web applications (either exploded or in a WAR format) from either the host where running the tc Runtime instance or from the local computer running your browser. When deploying from the host, you must specify the context path that users use to invoke the application. For detailed information about Tomcat Manager, see the Manager App How-To on the Apache Tomcat Web site. Deploying Multiple Versions of the Same Application When you create an instance using tc Runtime 7, you can deploy multiple versions of the same web application. This makes it possible to upgrade applications without interruption. Users who have a session in process continue to use the existing version of the application, but new sessions use the latest version of the application. To deploy a new version of an existing application using static deployment, append a version number to the context name, separated by two hash signs: contextname##version. For example, if you have already statically deployed a WAR file named myapp.war and you want to upgrade to version 2.0, you can deploy the new WAR file myapp##02.0.war. If you use the Hyperic user interface to deploy a new version, do not rename the WAR file. The tc Server Hyperic plug-in automatically appends the version number for you. Users continue to use the same URL to access the application; they do not include the version number. New sessions use the highest version deployed. Existing sessions continue to use the version that is already managing their session. If tc Runtime cannot locate the session in the SessionManager of an earlier version, the newest version is used. The version number is processed as a string, not as a number. This means that you can use letters in the version number, for example myapp##02b. It also means that you must be careful to ensure that your version numbers compare correctly. If the current version is myapp##9.0, deploying myapp##10.0 will not work as expected because the string "9.0" sorts higher than "10.0". When all sessions using an earlier version of an application have ended, the older version can be undeployed. Uninstalling tc Server: Typical Steps Uninstall one or more of these components as you wish: Hyperic Server Hyperic Agent tc Runtime Uninstallation of tc Server mostly entails removing the directories that contain the component files, although a few extra steps might be required, as described below. Each section covers both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\). WARNING: The procedures in this section describe how to completely remove the components of tc Server from your computer. Uninstalling Hyperic Server To uninstall the Hyperic Server component of tc Server: 1. Start a terminal window (Unix) or Command Prompt (Windows). 2. If currently running, stop the Hyperic Server. See Starting and Stopping the Hyperic Server and Agents. 3. Windows only. If you installed the Hyperic Server as a Windows service, change to the HQ_SERVER_INSTALL_DIR\bin directory (where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the Hyperic Server, such as \opt\vmware\hyperic\server-4.6.x.x-ee) and uninstall the service using the following command: 66 Post-Installation Tasks

71 Post-Installation Tasks 67 prompt> \opt\vmware\hyperic\server-4.6.x.x-ee\bin prompt> hq-server.exe -u 4. Remove the directory in which you installed the Hyperic Server, such as /opt/vmware/hyperic/ server-4.6.x.x-ee: prompt$ cd /opt/vmware/hyperic prompt$ rm -rf server-4.6.x.x-ee Uninstalling Hyperic Agent To uninstall the Hyperic Agent component of tc Server: 1. If the agent itself is managed by Hyperic, remove the platform for the agent using the Hyperic user interface. 2. Start a terminal window (Unix) or Command Prompt (Windows). 3. If currently running, stop the Hyperic Agent. See Starting and Stopping the Hyperic Server and Agents. 4. Windows only. If you installed the Hyperic Agent as a Windows service, you should now uninstall it. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the Hyperic Agent, such as \opt\vmware\hyperic\agent-4.6.x.x-ee. Once in this directory, uninstall the service using the hq-agent.bat remove command. For example: prompt> cd \opt\vmware\hyperic\agent-4.6.x.x-ee\bin prompt> hq-agent.bat remove 5. Remove the directory in which you installed the Hyperic Agent. For example: prompt$ cd /opt/vmware/hyperic prompt$ rm -rf agent-4.6.x.x-ee Uninstalling tc Runtime The following procedure describes how to uninstall the tc Runtime and all its associated instances. 1. If currently running, stop all tc Runtime instances. See Starting and Stopping tc Runtime Instances. 2. Start a terminal window (Unix) or Command Prompt (Windows). 3. Windows only. If you installed any tc Runtime instances as Windows services, change to the CATALINA_BASE\bin directory of each instance (such as \var\opt\vmware\vfabric-tc-server-standard\myserver\bin) and uninstall the service using the following command: prompt> \var\opt\vmware\vfabric-tc-server-standard\myserver\bin prompt> tcruntime-ctl.bat uninstall 4. Remove the main tc Server installation directory. For example, if you installed Standard Edition, the delete command might look something like the following: prompt$ rm -rf /opt/vmware/vfabric-tc-server-standard By default, the home directory of all tc Runtime instances is under the main tc Server installation directory; if you used this default location when you created the tc Runtime instances with the tcruntime-instance script, then the preceding delete command also deleted all tc Runtime instances. 5. If you created any tc Runtime instances in locations other than the default tc Server installation directory, remove their corresponding home directories. VMware vfabric tc Server

72 68 Getting Started with tc Server 68 Post-Installation Tasks

73 Upgrade and Migration Guide Upgrade and Migration Guide This chapter describes how to perform the following supported upgrade procedures: Upgrading a vfabric tc Server 2.1.X Installation to 2.6 Upgrading a 2.6.X tc Runtime to the Latest Version Upgrading a 2.0.X, 2.1.X, or 2.5.X tc Server Installation to 2.6 This section describes how to upgrade an existing 2.0.X, 2.1.X, or 2.5.X tc Server installation to tc Server 2.6.X. The upgrade procedure includes the following tasks: Upgrade Hyperic Server to vfabric Hyperic 4.6 Install Hyperic Agent 4.6 on computers that have tc Runtime Install tc Server 2.6 Upgrade existing tc Runtime instances to 2.6 Upgrade Hyperic Server to Hyperic 4.6 If you are using an older version of Hyperic Hyperic Server, Hyperic 4.6 Server includes new features and support for new releases of supported resources. To take advantage of these improvements in Hyperic 4.6, upgrade Hyperic Server on the computer where it is installed. The Hyperic 4.6 setup has an upgrade mode that updates an existing Hyperic Server installation. For complete instructions, see "Upgrade Hyperic Components/Server Upgrade Procedure" in vfabric Hyperic Installation Guide. Install Hyperic Agent 4.6 After you have upgraded Hyperic Server to Hyperic 4.6, you can use the Hyperic user interface to upgrade Hyperic Agents on computers with tc Runtime instances. Follow the instructions to upgrade Hyperic components in "Upgrade Hyperic Components/ Agent Upgrade Procedure" in vfabric Hyperic Installation Guide. Install tc Server 2.6 Install tc Server 2.6 in a new installation directory and create any new tc Runtime instances you want. Follow the instructions at Installing tc Server to perform the installation. To avoid overwriting files, be sure to install tc Server 2.6 in a different directory than your current installation. For example, if you have installed tc Server 2.1 in the directory /opt/vmware/ springsource-tc-server-2.1, you can install vfabric tc Server 2.6 in the directory /opt/vmware/vfabric-tcserver-2.6. Upgrade Existing tc Runtime Instances to 2.6 Use the tcruntime-instance.sh bat upgrade command to upgrade your tc Server 2.0 or 2.1 runtime instances to tc Server 2.6. The upgrade command, new in tc Server 2.6, migrates configuration information and applications from an existing instance to a new 2.6 instance. By default, the upgrade command creates a new instance that uses the same version of tc Runtime as the current instance. If you want to keep the same tc Runtime version, you must ensure that the corresponding tc Runtime release exists in your tc Server 2.6 installation directory. Otherwise, the upgrade command will display an error message and quit. If necessary, copy the tc Runtime release directory from the previous tc Server installation directory into the tc Server 2.6 installation directory. The script creates the upgraded instances in your tc Server 2.6 installation directory. For example, to upgrade the tc Server 2.1 instance at /opt/vmware/springsource-tc-server-2.1/myinstance, enter the following command in your tc Server 2.6 directory: VMware vfabric tc Server

74 70 Getting Started with tc Server prompt$./tcruntime-instance.sh upgrade../springsource-tc-server-2.1/myinstance This command creates an upgraded instance with the same name as the original (myinstance) using the same version of tc Runtime. To change the name of the upgraded instance, include the -i instancedir option on the command. To specify a different tc Runtime version, include the -v version option. When upgrading an unpinned instance, you must specify this option. The following example specifies a new instance name and pins the instance to tc Runtime release A.RELEASE. prompt$./tcruntime-instance.sh upgrade -i mynewinstance -v A.RELEASE../springsource-tc-server-2.1/myInstance See tcruntime-instance.sh Reference for more information about using this command. Upgrading a 2.6.X tc Runtime to the Latest Version The procedure in this section describes how to upgrade a tc Runtime installation (such as 2.6.0) to a later version (such as 2.6.1). The instructions assume your existing tc Runtime environment is the result of following the Quick Start instructions This section does not describe in detail how to upgrade your existing Hyperic components because those tasks follow the standard Hyperic upgrade procedures. You can follow the instructions in the section to upgrade a tc Runtime 2.6.X release to a later 2.6.X release. If you want to upgrade from an earlier release, for example from 2.1.X to 2.6.X, follow the instructions at Upgrading a 2.1.x tc Server Installation to 2.6. Understanding the Overall tc Server Upgrade Process Upgrading a 2.6.X tc Server installation to a later version consists of the following subtasks: Optionally upgrade your existing Hyperic Server and Agent to a later version than you have currently installed. See the Release Notes for the fully-qualified version of the Hyperic Server and Agent that a particular version of tc Server supports. The release notes also indicate the version of Hyperic that contains a particular version of the tc Server Hyperic plug-in. To perform this subtask, you download the Hyperic EE distribution and use its setup.sh -upgrade (Unix) or setup.bat -upgrade (Windows) command script to perform the upgrade. To upgrade an existing Hyperic Agent, unzip the latest version alongside the existing one. For details, see "Upgrade Hyperic Components" in vfabric Hyperic Installation Guide. Install the new 2.6.X tc Runtime in a new directory. To perform this subtask, unzip the appropriate tc Server distribution into a newly created installation directory. Then, if required, use the tcruntime-instance.sh upgrade command to upgrade each tc Runtime instance. For details, see the next section. Depending on how you have configured your tc Server installation, you might perform different subtasks on different computers. For example, on the computer on which you have installed the Hyperic Agent and runtime component (called a managed node), you perform only the Agent and Runtime upgrade. On the computer on which you installed the Hyperic Server (and nothing else), you perform only the Hyperic Server upgrade. If you installed all components on the same computer, then simply execute all subtasks on the same computer. Most of the examples in this section use Unix syntax; if you are upgrading on Windows, change the forward slashes to backslashes and replace the *.sh suffix with *.bat when running a command script. Other changes between the two platforms are called out. 70 Upgrade and Migration Guide

75 Upgrade and Migration Guide 71 tc Runtime Upgrade Procedure The examples in this procedure assume you are upgrading a tc Runtime to version (unless otherwise noted.) The procedure describes only how to upgrade the tc Runtime and associated instances. To upgrade Hyperic components follow the instructions in "Upgrade Hyperic Components" in vfabric Hyperic Installation Guide. To upgrade your 2.6.X tc Runtime to a later 2.6.X version, follow these steps: 1. Unix only: Read Important Note When Installing on Unix Platforms to ensure your tar command works with tc Server bundles. 2. Back up your existing tc Runtime installation, including all your tc Runtime instances. 3. Start a terminal (Unix) or Command Prompt (Windows). 4. If they are running, stop your tc Runtime instances. For example, if you installed tc Runtime in /opt/vmware/ vfabric-tc-server-standard release and you have a tc Runtime instance called myserver: prompt$ cd /opt/vmware/vfabric-tc-server-standard release prompt$./tcruntime-ctl.sh myserver stop If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCEDIR/bin/tcruntime-ctl.sh script to stop the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example: prompt$ cd /var/opt/vmware/vfabric-tc-server-standard//myserver/bin prompt$./tcruntime-ctl.sh stop 5. Windows only. If you installed the tc Runtime instances as Windows services, uninstall them. For example, if you installed the runtime in \opt\vmware\vfabric-tc-server-standard release and you created a tc Runtime instance called myserver: prompt> cd \opt\vmware\vfabric-tc-server-standard release prompt> tcruntime-ctl.bat myserver uninstall If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCEDIR\bin\tcruntime-ctl.bat script to stop the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example: prompt> cd \var\opt\vmware\vfabric-tc-server-standard\myserver\bin prompt> tcruntime-ctl.bat uninstall See Windows: Starting and Stopping tc Runtime Instances as Windows Services. 6. Download the appropriate tc Server distribution file from the VMware Download Center. Typically, you download the Standard Edition of tc Server in either the compressed TAR or ZIP format; for example: vfabric-tc-server-standard release.tar.gz vfabric-tc-server-standard release.zip 7. Unzip or untar the new 2.6.X package into a new directory, parallel to your existing tc Server installation. For example, if your existing tc Server is installed in /opt/vmware/vfabric-tc-server-standard release and you downloaded the new package into the /home/downloads directory: prompt$ cd /opt/vmware prompt$ unzip /home/downloads/vfabric-tc-server-standard release.zip The preceding command creates a new directory alongside the existing tc Server installation directory. VMware vfabric tc Server

76 72 8. Getting Started with tc Server Upgrading tc Runtime instances. This step describes how to upgrade your existing tc Runtime instances to the new version. From your terminal (Unix) or Command Prompt (Windows), change to the new tc Server installation directory. For example: prompt$ cd /opt/vmware/vfabric-tc-server-standard release For each existing tc Runtime instance you want to upgrade, run the following command: prompt$./tcruntime-instance.sh upgrade --instance-directory instancedir instance where: instancedir refers to the full or relative pathname of the directory in which the instance lives. instance refers to the name of the subdirectory that contains the tc Runtime instance you want to upgrade, such as myserver For example, to upgrade an instance named myserver from tc Server to tc Server 2.6.1, issue these commands: prompt$ cd /opt/vmware/vfabric-tc-server-standard release prompt$./tcruntime-instance.sh upgrade --instance-directory../tc-server-standard release myserver Because you do not specify a specific tc Runtime version, the tcruntime-instance.sh bat script pins the instance to the latest version of tc Runtime it can find when it starts. Generally, this is the tc Runtime version bundled with the new tc Server distribution you are installing. The upgrade command cannot change the major tc Runtime version (tc Runtime 6 or tc Runtime 7), but it will upgrade the instance to the latest minor version available in the tc Server installation directory. 9. Start the tc Runtime instances as described in Starting and Stopping tc Runtime Instances. The startup messages should indicate that the instance is now using the latest tc Runtime version (such as A) as its core. For example: prompt$ cd /opt/vmware/vfabric-tc-server-standard release prompt$./tcruntime-ctl.sh myserver start INFO Instance name: myserver INFO Script directory: /opt/vmware/vfabric-tc-server-standard release INFO tc Runtime location:/opt/vmware/vfabric-tc-server-standard release INFO Instance base: /opt/vmware/vfabric-tc-server-standard release INFO Binary dir: /opt/vmware/vfabric-tc-server-standard release/tomcat a.release INFO Runtime version: A.RELEASE INFO Script version: RELEASE Using CATALINA_BASE: /opt/vmware/vfabric-tc-server-standard release/myserver Using CATALINA_HOME: /opt/vmware/vfabric-tc-server-standard release/tomcat a.release Using CATALINA_TMPDIR: /opt/vmware/vfabric-tc-server-standard release/myserver/temp Using JRE_HOME: /var/opt/java/jdk1.6.0_24 Using CLASSPATH: /opt/vmware/vfabric-tc-server-standard release/myserver/bin/tomcat-juli.jar: /opt/vmware/vfabric-tc-server-standard release/tomcat a.release/bin/bootstrap.jar When you complete this procedure, you will have successfully upgraded your existing 2.6.X tc Runtime to a later version of Upgrade and Migration Guide

77 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances This tutorial describes the basic steps for configuring and monitoring a tc Runtime instance with the Hyperic user interface and for managing applications deployed to the instance. 1. Before You Begin 2. Restart a tc Runtime Instance 3. Reconfigure a tc Runtime Instance 4. Deploy a Web Application to a tc Runtime Instance 5. Add a tc Runtime Instance to the Favorite Resources Portlet 6. Create an Hyperic Group of Multiple tc Runtime Instances 7. Monitor a tc Runtime Instance 8. View, Configure, or Disable the Preconfigured Deadlock Detection Alert Before You Begin Install and start the components of vfabric tc Server (Hyperic Server, Hyperic Agent, and at least one tc Runtime instance); invoke the Hyperic user interface in your browser; and log in with the administration username/password (default hqadmin/ hqadmin) or with Hyperic user permissions to configure a tc Runtime instance. To accomplish these tasks, see: Installing tc Server Creating a New tc Runtime Instance Starting and Stopping tc Runtime Instances Starting and Stopping the Hyperic Server and Agents Getting Started with the Hyperic User Interface Most Hyperic user interface pages have a Help link at the top-right corner. On the tc Runtime configuration pages, click the icon to the right of each field to get information about the field. For simplicity, it is assumed in this tutorial that you are going to log in to the Hyperic user interface as the superuser (hqadmin). If, however, you are going to log in as a non-superuser, see "User Permissions Required to Use the tc Server Hyperic Plugin Features" in vfabric tc Server Administration for information about the required Hyperic user permissions to be able to use all the tc Server Hyperic plug-in features described in this tutorial. Restart a tc Runtime Instance In this procedure you restart a currently running tc Runtime instance. If you need navigational help for the first few steps, see Getting Started with the Hyperic user interface. 1. Click the Resources > Browse link at the top of the Hyperic user interface 2. Click the Servers (X) link to see the list of servers known by Hyperic. To limit the number of displayed servers to only tc Runtime instances, select SpringSource tc Runtime 6.0 or SpringSource tc Runtime 7.0 from the Search drop-down list, then click the green arrow to the far right. VMware vfabric tc Server

78 74 3. Getting Started with tc Server In the table, click the tc Runtime instance you want to restart. The server is listed as platform-resource tc Runtime catalina-base-dir, where platform-resource is the computer hosting the tc Runtime instance. catalina-base-dir is the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames, such as myserver. 4. Click the Control tab. You use this Hyperic user interface page to stop, start, and restart the current tc Runtime instance, as described in the next step. 5. In the Quick Control section of the page, select Restart from the Control Action drop-down list, then click the arrow to the right, as shown in the following graphic. After you click the restart button, the Command State field in the Current Status section says In progress until the tc Runtime instance is successfully restarted. The Current Status section always displays information about the last control action; in this case the restart of the tc Runtime instance. Reconfigure a tc Runtime Instance In this procedure you make a few simple configuration changes to the current tc Runtime instance. You change a startup-up JVM option (maximum heap size) and change the working directory of the default virtual host for the tc Runtime instance. It is assumed in this procedure that you have already browsed to the tc Runtime instance that you want to configure, as described in Restart a tc Runtime Instance Click the Views > Server Configuration tab: Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

79 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances 75 The server configuration pages consist of four tabs: Home: Main Server Configuration page. There is also an Advanced group for performing more advanced tasks, such as reloading the settings from the tc Runtime instance server.xml file (in which you lose local changes made with the Hyperic user interface), reverting to a previous server configuration, and uploading a new server configuration using a server.xml file. Configuration: Configure tc Runtime startup options, JVM options, context information for all deployed Web applications, default behavior of JSPs and static content, and so on. Resources: Create and configure JDBC datasources. Services: Create and configure tc Runtime services such as virtual hosts, connectors, and so on. 2. Click the Configuration tab, then the Server Start option in the list on the left. VMware vfabric tc Server

80 76 Getting Started with tc Server 3. In the General section on the right, enter 1024 in the Max Heap Size (MB) field. 4. Click Save at the bottom of the page. The message Configuration saved successfully appears at the top, as shown in the following graphic. This means that Hyperic has updated its in-memory cache with your changes. Additionally, a box appears at the top of the page with the heading Changes have been made locally, along with two links to either write (push) the changes to the actual tc Runtime configuration files, such as CATALINA_HOME/bin/setenv.sh (in this case) or CATALINA_BASE/ conf/server.xml, or to undo the changes. 76 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

81 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances 77 Hyperic displays this box until you save or undo, although you can make additional changes before you save or undo. In this tutorial, you make another change, and then write the changes to disk. 5. Click the Services tab. In the table, click the Catalina service. This is the default service of tc Runtime. 6. In the list on the left, click Hosts, then in the table on the right, click the localhost virtual host. VMware vfabric tc Server

82 78 Getting Started with tc Server 7. In the Host Properties section, enter new_work_dir in the Work Directory field. This specifies that the localhost will use a different work directory from the default, which is CATALINA_BASE/work. Relative work directories are created under CATALINA_BASE, such as CATALINA_BASE/new_work_dir. The tc Runtime instance uses the work directory to perform its internal work. 8. Click Save at the bottom of the page. The message Configuration saved successfully appears in the top. When you update the tc Runtime configuration using the Hyperic user interface, if the property you are updating was previously specified as a variable (such as ${jmx.port}), tc Runtime replaces that variable with the actual value in the server.xml file. This means, for example, that port="${jmx.port}" would become port="6954". The variable is still set in the catalina.properties file to the old value, but the tc Runtime does not actually use it because the property is now hardcoded in the server.xml file. 9. In the box at the top titled Changes have been made locally, click Push configuration changes to Tomcat. 10. Click Push Changes to Server. 11. In the box at the top, click the restarted link to restart the tc Runtime instance so that the changes take effect. 78 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

83 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances Click Restart Server. The message Server Restarted appears at the top. Deploy a Web Application to a tc Server Runtime Instance In this procedure you deploy a new Web application to a tc Runtime instance, then stop and start it. It is assumed that you already have a Web application WAR file to deploy. If you do not, see Tutorial: Very Simple Web Application Development for a tutorial that shows you how to create a very simple HelloWorld Web application and package it into a WAR file. It is also assumed that you have already browsed to the tc Runtime instance to which you want to deploy, as described in Restart a tc Runtime Instance. 1. Click the Views > Application Management tab. You use this page to deploy and manage tc Runtime applications. 2. If the Web application you want to deploy is physically located on the same computer from which you are running your browser, go to the Deploy Application from Local Machine section. If the Web application is actually located on the computer on which the tc Runtime instance is running, then go to the Deploy Application from Server Machine section. VMware vfabric tc Server

84 80 Getting Started with tc Server If you are running your browser on the same computer as tc Runtime, then you can go to either section. A typical remote machine use case is machines that use network mounted drives to which they have access. Enter the location of the Web application in the corresponding field. Use the Browse button to find a local Web application WAR file; you must already know the full pathname of the WAR file if you are deploying it from the tc Runtime computer. If you are deploying from a remote machine, your local machine must have access to the remote directory that contains the Web application file. The following graphic shows deploying from a local computer 3. Enter hello in the Context path field. Optionally, check the Use cold deployment strategy if you want the tc Runtime instance to shutdown, deploy the application, and then start up again. By default (if box is unchecked), the tc Runtime instance hot-deploys the application, which means it does not shutdown then restart but simply deploys the application while the instance is still running. Use the cold deployment strategy if you want to avoid common hot deployment errors, such as running out of PermGen space. The PermGen space holds the metadata about classes that have been loaded/created in the JVM Click Upload and deploy (for a local WAR file) or Deploy (for deploying a WAR file on the tc Runtime computer). Hyperic deploys the WAR file to the current tc Runtime instance. You should see the Web application listed in the Deployed Applications table. Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

85 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances 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: where: host is the name of the computer on which the tc Runtime instance is running. If it is the same computer as your browser, you can enter localhost. port is the TCP/IP port to which the tc Runtime instance listens. The default value is For example: You can get the host and port information of a tc Runtime instance by looking at its HTTP connector configuration from the Views > Server Configuration > Services tab. Add tc Runtime Instances to the Favorite Resources Portlet The main Hyperic dashboard includes a Favorite Resources portlet that lists the resources you most often manage. When you first install Hyperic, the portlet is empty. However, as you manage a particular resource, you might decide that you want to add it to your favorites portlet because you return to it frequently. In this procedure you add a tc Runtime instance to the Favorite Resources portlet. 1. Navigate to the tc Runtime instance, as described in the first three steps of Restart a tc Runtime Instance. 2. Click the Tools Menu in the top-left corner and choose Add to Dashboard Favorites. VMware vfabric tc Server

86 82 Getting Started with tc Server 3. In the box, click the name of the user for whose dashboard the tc Runtime instance will show up as a favorite. Following our tutorial, click hqadmin, although if you logged in as another user you can enter that one. 4. Click Add. 5. The tc Runtime instance is displayed in the Favorite Resources portlet on the main dashboard: Create an Hyperic Group of Multiple tc Runtime Instances In this procedure you create an Hyperic group of multiple tc Runtime instances. You can then deploy a Web application to the group in a procedure similar to Deploy a Web Application to a tc Server Runtime Instance, and Hyperic does the work of deploying the Web application to each member of the group. Similarly, you can stop, start, and restart all the servers in the group with a procedure similar to Restart a tc Runtime Instance. Using Hyperic groups saves a lot of time if you need to control multiple tc Runtime instances running on many different computers, as well as deploy and manage their applications. It is assumed in this procedure that you have at least two tc Runtime instances running and that you have added them to the Hyperic inventory. See Creating a New tc Runtime Instance and Getting Started with the Hyperic User Interface. It might take a while for the Hyperic user interface to auto-detect a new tc Runtime instance after you start it. You can force a new auto-discovery to speed the process. To force an auto-discovery, browse to the platform resource where you started the new tc Runtime instance. For example, in this tutorial the platform resource is called juliet-desktop. Then click New Auto-Discovery in 82 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

87 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances 83 the Tools Menu. In the Quick Auto-Discovery Scan section, click OK. The new tc Runtime instance should show up in the Auto-Disocvery portlet of the main Dashboard very shortly. You can then add it using the Add to Inventory button as usual. 1. Click the Resources > Browse link at the top of the Hyperic user interface. 2. Click the Servers (X) link to list all the servers in your resource inventory. The tc Runtime instances are listed as Server Type SpringSource tc Runtime 6.0 or SpringSource tc Runtime 7.0. If there are many server resources listed in the table, you can narrow down the list by selecting a server type in the Search drop-down list, then clicking the green arrow all the way to the right of the Search line. 3. For each tc Runtime instance you want to include in the new group, check the box to the left of the instance's entry in the table. Note that the Hyperic UI itself internally uses an instance of tc Runtime (called hq-server); you should not change the configuration of this instance or add it to your groups. 4. Click Group. The following graphic shows how to group together two tc Runtime instances called tc Runtime anotherserver and tc Runtime myserver. 5. In the Group Manager window, click Add to New Group. 6. In the General Properties section, enter a name for the group, such as tcservergroup and an optional description and location, such as San Francisco. 7. Click OK. Depending on the members of the group, Hyperic creates a Compatible Group/Cluster or Mixed Group. The first type of group consists of a single type of server, such as only tc Runtime instances. The second mixed group consists of different types of servers, such as both tc Runtime instances and Apache Tomcat servers. To stop or restart the group of servers, and deploy an application to the group: 1. Click Resources > Browse at the top of the Hyperic user interface. 2. Click Compatible Groups/Clusters if your group consists of the same servers, or Mixed Groups if your group consists of different types of servers. VMware vfabric tc Server

88 84 Getting Started with tc Server 3. In the table, click on the name of the group. 4. To stop or start all the servers in the group, click the Control tab, then follow the steps for controlling a single server, as described in Restart a tc Runtime Instance. The breadcrumbs at the top of the console page list the group name (tcservergroup in this case) rather than the tc Runtime instance name. 5. To deploy and manage applications on all servers in the group, click the Views > Application Management tab, then follow the steps for deploying or managing the applications of a single server, as described in Deploy a Web Application to a tc Server Instance. In this release of tc Server, you cannot update the configuration of a group of tc Runtime instances from the Views > Server Configuration tab. You can update the configurations of servers in a group using the tcsadmin command-line interface. See "Using the tcsadmin Command-Line Interface" in vfabric tc Server Administration Guide. Monitoring tc Runtime Instances As soon as you add a resource (such as a tc Runtime instance) to the Hyperic inventory, Hyperic begins collecting a variety of metrics about the resource that you can use to monitor its state and health. Hyperic displays the values of the metrics over a specified period of time using indicator charts or tables. Examples of the types of metrics that Hyperic collects about tc Runtime include: Number of thread deadlocks detected. Size of the free heap memory. JSP count per minute. Number of servlet requests per minute. The following procedure describes how to view the monitoring metrics for a tc Runtime instance. 1. Navigate to the tc Runtime instance, as described in the first three steps of Restarting the tc Runtime Instance. 2. Click the Monitor tab. The charts under the Indicator tab show data about the entire tc Runtime instance, such as thread deadlocks detected and size of the free heap memory and the tc Runtime instance up time. Click the Metric Data tab to see the same information in tabular form. The Services table to the left lists the services associated with the tc Runtime instance, such as the JSP and servlet monitors. 84 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

89 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances 3. In the Services table, click SpringSource tc Runtime Servlet Monitor. The chart on the right shows usage metrics about the servlets deployed to the tc Runtime instance. 4. Click on other services within the Monitoring tab to view more monitoring information for the tc Runtime instance. 85 You can create an alert for a resource that fires when a specified condition is met, and optionally specify a control action that occurs when the alert is fired. Hyperic is preconfigured for a deadlock detection alert; see Manage the Preconfigured Deadlock Detected Alert to modify it. Manage the Preconfigured Deadlock Detected Alert Hyperic includes a preconfigured alert that triggers once if the Deadlocks Detected metric exceeds 0. Hyperic applies this alert to all auto-discovered tc Runtime instances, enables it by default, and then checks the metric every two minutes to see if the condition has been met. After triggering, Hyperic disables the alert until an administrator marks it as Fixed. The following procedure describes how to view this preconfigured alert, modify it so that Hyperic automatically restarts the tc Runtime instance in which the alert is triggered, and then disable it. 1. Navigate to the tc Runtime instance, as described in the first three steps of Restart a tc Runtime Instance. 2. Click the Alert tab at the top of the page. 3. Click the Configure button. A page is displayed with a table of alerts that have been defined for this tc Runtime instance. You should see the preconfigured Deadlocks Detected alert; by default it is active (enabled.) 4. In the table, click Deadlocks Detected to display the Alert Definition page. 5. Click the Control Action tab at the bottom of the page, and then click the EDIT... button. VMware vfabric tc Server

90 86 Getting Started with tc Server 6. Select restart from the Control Type drop-down list. 7. Click OK. You have modified the alert so that Hyperic automatically restarts the affected tc Runtime instance when Hyperic detects a thread deadlock To disable the alert: 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. Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

91 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances d. 87 Click the arrow to the right of the drop-down list. The Active column for the Deadlocks Detected alert changes to No. VMware vfabric tc Server

92 88 Getting Started with tc Server 88 Tutorial: Using Hyperic to Configure and Manage tc Runtime Instances

93 Tutorial: Very Simple HelloWorld Web Application Tutorial: Very Simple HelloWorld Web Application This tutorial is for beginning programmers who want to know the minimal basic information on how to create servlets and JSPs, package them into a deployable WAR file, deploy the application to a tc Runtime instance, and run the application in a browser. The tutorial uses Ant as its build framework. You can also use an IDE, such as SpringSource Tool Suite, to create the application. The tutorial shows you how to create each artifact, from the servlet source to the Ant build.xml file, from scratch. Before You Begin Install vfabric tc Server and Ant. See Installing tc Server and Apache Ant Project. Creating and Deploying the HelloWorld Web Application To create a Web application and deploy it to a tc Runtime instance: 1. When you install Ant, add or update the following environment variables: ANT_HOME: Set this variable to the location where you installed Ant, such as /usr/local/ant/apacheant PATH: Update your PATH variable to include ANT_HOME/bin. 2. Set the JAVA_HOME environment variable to the directory where the JDK is installed. 3. Create a project directory structure to contain the HelloWorld Web application source files. Create the top-level directory called helloworld. You can create the helloworld directory in any location on your computer that you have permission to update. The helloworld directory will contain the Ant build file (build.xml). Create two sub-directories of the helloworld directory: src to contain the Java source file for the HelloWorld servlet and web that will contain the JSP file, static HTML file, images, and deployment descriptor. In the src directory, create an examples sub-directory. This directory corresponds to the package that contains the HelloWorld servlet. In the web directory, create two subdirectories: images, which will contain any images used by the Web application, and WEB-INF, which is a standard directory that contains the Web application deployment descriptor files. The following graphic describes the project directory hierarchy: Figure 9.1. medirectory Hierarchy of the HelloWorld Application 4. Create the Hello.java servlet Java source file and put it in the helloworld/src/examples directory. For sample Java code that you can copy and paste into your own Java file and a brief explanation of how to program a simple servlet, see Hello.java. VMware vfabric tc Server

94 90 5. Getting Started with tc Server Create the hello.jsp JSP file and put it in the helloworld/web directory. For sample JSP code that you can copy and paste into your own JSP file and a brief explanation of how to program a simple JSP, see hello.jsp. 6. Create the web.xml Web application deployment descriptor and put it in the helloworld/web/web-inf directory. For sample XML that you can copy and paste into your own web.xml file and a brief explanation of the elements, see web.xml. 7. Create the default index.html page and put it in the helloworld/web directory. For a sample HTML file that you can copy and paste into your own file, see index.html. 8. Create the Ant build file (build.xml) that includes targets for compiling and packaging the Web application and put it in the helloworld directory. For a sample Ant build file that you can copy and paste into your own file, see build.xml. 9. In your own build file, update the tcserver.home property to fit your environment; it should point to the CATALINA_HOME of your tc Runtime installation. For example, if you installed tc Server Standard Edition in the /opt/ vmware directory, set the tcserver.home property in the build.xml file to something like the following: <property name="tcserver.home" value="/opt/vmware/vfabric-tc-server-standard/tomcat a.release" /> 10. Right-click the following image and save it with name springsource.png to the helloworld/web/images directory. When you finish creating all the artifacts that make up the HelloWorld Web application, your directory structure and contents should look like the following: helloworld helloworld/build.xml helloworld/src helloworld/src/examples helloworld/src/examples/hello.java helloworld/web helloworld/web/hello.jsp helloworld/web/images helloworld/web/images/springsource.png helloworld/web/index.html helloworld/web/web-inf helloworld/web/web-inf/web.xml 11. Compile and package the HelloWorld Web application by opening a command window, changing to the helloworld directory, and executing the following command: prompt> ant all This ant command creates a deployable WAR file of the HelloWorld application called hello.war in the helloworld/dist directory. You will see the following output from the ant command if it completes successfully: 90 Tutorial: Very Simple HelloWorld Web Application

95 Tutorial: Very Simple HelloWorld Web Application 91 Buildfile: build.xml clean: prepare: [mkdir] Created dir: /home/samples/helloworld/dist [mkdir] Created dir: /home/samples/helloworld/work/web-inf/classes [copy] Copying 4 files to /home/samples/helloworld/work compile: [javac] Compiling 1 source file to /home/samples/helloworld/work/web-inf/classes dist: [jar] Building jar: /home/samples/helloworld/dist/hello.war all: BUILD SUCCESSFUL Total time: 2 seconds 12. Start a tc Runtime instance. See Starting and Stopping tc Runtime Instances. 13. Deploy the Web application JAR file to the tc Runtime instance. See Deploying Applications to tc Runtime Instances. 14. Invoke the HelloWorld Web application in your browser: where: host is the name of the computer that is hosting the tc Runtime instance. If it is the same as the computer hosting your browser, you can use localhost. port is the port to which the tc Runtime instance listens. The default value is In the example, /hello is the default URL context of the Web application, which in this example is the name of the WAR package without the trailing.war file extension. For example: 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 import import import import import java.io.ioexception; java.io.printwriter; javax.servlet.servletexception; javax.servlet.http.httpservlet; javax.servlet.http.httpservletrequest; javax.servlet.http.httpservletresponse; /** * Simple Hello servlet. */ public final class Hello extends HttpServlet { VMware vfabric tc Server

96 92 Getting Started with tc Server /** * Respond to a GET request for the content produced by * this servlet. * request The servlet request we are processing response The servlet response we are producing * IOException if an input/output error occurs 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 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. 92 Tutorial: Very Simple HelloWorld Web Application

97 Tutorial: Very Simple HelloWorld Web Application 93 <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 compiletime, the JSP is converted into a servlet, which is what tc Runtime instance actually executes at runtime. The hello.jsp includes the following simple JSP directive: <%= new String("Hello!") %> This JSP directive simply prints out a message to the client (browser): Hello! For complete documentation about JSPs, including specifications, FAQs, and tutorials, see JavaServer Pages Technology. Sample web.xml File The following sample web.xml deployment descriptor shows how to declare the HelloServlet servlet in the HelloWorld Web application. See also Description of the web.xml File. <?xml version="1.0" encoding="iso "?> <web-app xmlns=" xmlns:xsi=" xsi:schemalocation=" 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> VMware vfabric tc Server

98 94 Getting Started with tc Server </servlet> <servlet-mapping> <servlet-name>helloservlet</servlet-name> <url-pattern>/hello</url-pattern> </servlet-mapping> </web-app> Description of the web.xml File In the preceding web.xml deployment descriptor file, the <servlet> XML element declares the HelloServlet, the examples.hello Java class implements the servlet, and the <servlet-mapping> XML element specifies the /hello URL pattern that invokes the servlet in a browser. This URL pattern is used in the index.html file. 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 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="hello"/> <property name="tcserver.home" value="/opt/vmware/vfabric-tc-server-standard/tomcat a.release" /> <property name="work.home" value="${basedir}/work"/> <property name="dist.home" value="${basedir}/dist"/> <property name="src.home" value="${basedir}/src"/> <property name="web.home" value="${basedir}/web"/> 94 Tutorial: Very Simple HelloWorld Web Application

99 Tutorial: Very Simple HelloWorld Web Application 95 <target name="help"> <echo>you can use the following targets:</echo> <echo> </echo> <echo> help : (default) Prints this message </echo> <echo> all : Cleans, compiles, and packages application</echo> <echo> clean : Deletes work directories</echo> <echo> compile : Compiles servlets into class files</echo> <echo> dist : Packages artifacts into a deployable WAR</echo> <echo></echo> <echo>for example, to clean, compile, and package all at once, run:</echo> <echo>prompt> ant all </echo> </target> <!-- Define the CLASSPATH --> <path id="compile.classpath"> <fileset dir="${tcserver.home}/bin"> <include name="*.jar"/> </fileset> <pathelement location="${tcserver.home}/lib"/> <fileset dir="${tcserver.home}/lib"> <include name="*.jar"/> </fileset> </path> <target name="all" depends="clean,compile,dist" description="clean work dirs, then compile and create a WAR"/> <target name="clean" description="delete old work and dist directories"> <delete dir="${work.home}"/> <delete dir="${dist.home}"/> </target> <target name="prepare" depends="clean" description="create working dirs and copy static files to work dir"> <mkdir dir="${dist.home}"/> <mkdir dir="${work.home}/web-inf/classes"/> <!-- Copy static HTML and JSP files to work dir --> <copy todir="${work.home}"> <fileset dir="${web.home}"/> </copy> </target> <target name="compile" depends="prepare" description="compile Java sources and copy to WEB-INF/classes dir"> <javac srcdir="${src.home}" destdir="${work.home}/web-inf/classes"> <classpath refid="compile.classpath"/> </javac> <copy todir="${work.home}/web-inf/classes"> <fileset dir="${src.home}" excludes="**/*.java"/> </copy> </target> <target name="dist" depends="compile" description="create WAR file for binary distribution"> <jar jarfile="${dist.home}/${app.name}.war" basedir="${work.home}"/> </target> </project> Description of the build.xml File The Ant build.xml file defines targets for compiling and packaging the HelloWorld Web application. In preparation, the build process first creates an output directory and creates the required directory hierarchy below it for a standard Web application. This VMware vfabric tc Server

100 96 Getting Started with tc Server includes the WEB-INF directory that will contain the web.xml file. The build process also sets the build's CLASSPATH value to include the required JAR files in the tc Server distribution. The compile target uses the Java compiler to compile the Java servlet file into a class and copies it to the output directory. The package target creates a JAR file of the output directory. 96 Tutorial: Very Simple HelloWorld Web Application

101 Troubleshooting Troubleshooting The following sections describe common problems and resolutions. Hyperic: Resources Not Showing up in the Hyperic User Interface Hyperic: Errors When Trying to Add an Auto-Discovered Resource Hyperic Agent: Errors When Starting on Solaris tc Runtime: Hot Redeploy/Stop/Undeploy on Windows Fails tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite tc Runtime: JVM Performing a Full GC Hyperic: Resources Not Showing up in the Hyperic User Interface By default, an Hyperic Agent checks for new resources only once a day. For example, if you start the Hyperic Server and Hyperic Agent, and then create a new tc Runtime instance and start it, you might have to wait 24 hours for the new tc Runtime instance to be auto-discovered by Hyperic. You can force an auto-discovery of new resources in two ways: Stop and start the Hyperic Agent on the computer for which you want to force an auto-discovery. When the Hyperic Agent starts, it automatically checks for new resources. See Starting and Stopping the Hyperic Server and Agents for details. Use the Hyperic user interface to force an auto-discovery: 1. From the main dashboard, click the Resources > Browse link. 2. Click the Platforms(XX) link. 3. In the table, click on the name of the platform for which you want to force an auto-discovery. 4. In the top-right Tools Menu box, click New Auto-Discovery. 5. In the top section called Quick Auto-Discovery Scan, click OK. New resources show up in the Auto-Discovery portlet of the main dashboard as soon as Hyperic completes the scan of the platform. Hyperic: Errors When Trying to Add an Auto-Discovered Resource If you get errors when trying to add an auto-discovered resource to the Hyperic server using the user interface: 1. Log onto the platform that hosts the resource that is returning errors when you try to add it using the Hyperic user interface. 2. Stop the Hyperic Agent. See Starting and Stopping the Hyperic Server and Agents for details. 3. Change to the HQ_AGENT_INSTALL_DIR directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the Hyperic Agent, such as /opt/vmware/hyperic/agent-4.5.x.x-ee. 4. Remove the data directory. 5. Start the Hyperic Agent. Because you removed the data directory, the Agent operates as if this is a new installation, so the start script takes you through the configuration process for the Agent again. This step often clears up the auto-discovery errors and allows you to again add all new auto-discovered resources through the Hyperic user interface. VMware vfabric tc Server

102 98 Getting Started with tc Server Hyperic Agent: Errors When Starting on Solaris This section applies to Solaris platforms only. If you try to start the Hyperic Agent on Solaris and get errors similar to the following: prompt$ cd /opt/vmware/hyperic/agent ee/bin prompt$./hq-agent.sh start Bad string Unable to locate any of the following binaries: /opt/vmware/hyperic/agent ee/wrapper/sbin/../../wrapper/sbin/wrapper---32 /opt/vmware/hyperic/agent ee/wrapper/sbin/../../wrapper/sbin/wrapper---64 /opt/vmware/hyperic/agent ee/wrapper/sbin/../../wrapper/sbin/wrapper... make sure that you have set the locale correctly on your Solaris computer. In particular, the locale must not be set to a UTF-8 locale, such as en_us.utf-8. The following are sample settings for the LC_CTYPE environment variable that resolve the problem: LC_CTYPE=en_US LC_CTYPE=en_US.ISO LC_CTYPE=en_US.ISO tc Runtime: Hot Redeploy/Stop/Undeploy on Windows Fails Because of the way that file system locking works on Windows platforms, hot redeployment of a Web application on Windows can sometimes fail. Hot redeployment may also fail when you stop or undeploy a Web application on Windows. The problem can occur when you use the Hyperic user interface or the tcsadmin command-line interface. To resolve the problem: 1. Update the CATALINA_BASE/conf/context.xml file of the tc Runtime instance and set the following two attributes of the <Context> element to true: antijarlocking: When set to true, the tc Runtime classloader takes extra measures to avoid JAR file locking when resources are accessed inside JARs through URLs. This action affects the startup time of applications, but is useful on platforms (such as Windows) or configurations where file locking can occur. antiresourcelocking: When set to true, tc Runtime prevents any file locking. This action affects startup time of applications significantly, but allows full Web application hot redeploy on platforms (such as Windows) or configurations where file locking can occur. The following context.xml snippet shows how to specify the attributes; only the relevant part of the file is shown: <Context antijarlocking="true" antiresourcelocking="true"> <WatchedResource> Restart the tc Runtime instance for the change to take effect. Setting antijarlocking and antiresourcelocking to true forces tc Runtime to copy files rather than read them in place. Also, if you try to copy in a new.jsp file directly, tc Runtime does not pick it up. If you prefer, you can set these two properties in the context.xml file of the application itself rather than in the context.xml file for the entire tc Runtime instance. For more information and warnings about configuring the context.xml file, see The Context Container. 98 Troubleshooting

103 Troubleshooting 99 tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite When you use SpringSource Tool Suite (STS) with tc Server, and you try to run a Web application on the configured tc Runtime, you might get the following error: Nov 29, :47:29 PM com.springsource.tcserver.security.propertydecoder <init< INFO: tcserver property decoder has been initialized. Nov 29, :47:30 PM com.springsource.tcserver.serviceability.rmi.jmxsocketlistener init INFO: Started up JMX registry on :6969 Nov 29, :47:30 PM org.apache.coyote.http11.http11protocol init SEVERE: Error initializing endpoint java.net.socketexception: Unrecognized Windows Sockets error: 0: JVM_Bind at java.net.plainsocketimpl.socketbind(native Method) at java.net.plainsocketimpl.bind(plainsocketimpl.java :365) at java.net.serversocket.bind(serversocket.java:319) at java.net.serversocket.<init<(serversocket.java:185 ) at java.net.serversocket.<init<(serversocket.java:141 )... and so on STS might not have write permission to the main tc Server installation path, and the tc Runtime has to create files when it starts. Modify the path of tc Runtime in STS to use the workspace metadata. tc Runtime: JVM Performing a Full GC By default, tc Runtime instances have JMX turned on so that you can use Hyperic to monitor and manage the instances. Specifically, tc Runtime instances enable JMX using the JmxSocketListener in the server.xml configuration file, as shown: <Listener classname="com.springsource.tcserver.serviceability.rmi.jmxsocketlistener" port="${jmx.port}"... /> When JMX is enabled in this way, some JVMs (such as Sun's) that do distributed garbage collection will periodically invoke System.gc, causing a Full GC. This action can affect the performance of your deployed Web applications. There are two ways to work around this issue: Specify that the JVM invoke the System.gc() less often. For example, to configure the Sun JVM to invoke System.gc() at one-hour intervals, use the following JVM options: -Dsun.rmi.dgc.client.gcInterval= Dsun.rmi.dgc.server.gcInterval= Alternatively, disable explicit GC altogether. For example, to disable GC for the Sun JVM: -XX:+DisableExplicitGC In both cases, set these JVM options in the INSTANCE-DIR/bin/setenv.sh bat file using the JVM_OPTS variable appropriate to your platform. VMware vfabric tc Server

104 100 Getting Started with tc Server 100 Troubleshooting