Getting Started with vfabric tc Server

(1)

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 http://www.vmware.com/support/pubs.

(2)

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to: [email protected]

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

http://

www.vmware.com/download/patents.html

.

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 94304

www.vmware.com

(3)

1. About Getting Started with vFabric tc Server ... 1

Intended Audience ... 1

2. Quick Start ... 3

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

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

(6)

(7)

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 2.6.0.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-2.6.0.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-server-standard-version. This directory contains all the tc Runtime files and directories.

(8)

Create and start a tc Runtime instance

1. From your terminal window or Command Prompt, change to the tc Runtime directory and execute the tcruntime-instance command to create a basic tc Runtime instance (called myserver in the 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-2.6.0.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-2.6.0.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 http://host:8080, 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

(9)

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 non-VMware 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.

(10)

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

(11)

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

(12)

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

(13)

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

(14)

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

(15)

Figure 3.4. Installing on Multiple Computers

4. 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 Yes Yes

Java Server Pages (JSP) 2.1 support Yes Yes

HTTP session clustering Yes Yes

Advanced I/O features Yes Yes

Pre-built advanced non-blocking I/O components Yes Yes

Basic Windows service wrapper Yes Yes

Enterprise 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 Yes No

New high-concurrency JDBC connection pool` Yes No

Preconfigured for JMX management Yes No

Includes latest security vulnerability and bug fixes Yes Rebuild Tomcat yourself to apply incremental fixes.

Binary patch updates Yes Binary patches are not provided

by Tomcat community.

Unix boot scripts Yes No

(18)

Advanced Configuration Features

tc Runtime has a number of advanced configuration features that Apache Tomcat does not. Table 4.3. 1Advanced Configuration Feature Comparison

Advanced Configuration Features tc Runtime Apache Tomcat

Templated production-ready configuration out-of-the-box. Yes No

Create Tomcat single server configuration. Yes No

Modify general server configuration including JVM startup parameters. Yes No

Modify context container configuration. Yes No

Modify server defaults for JSPs and static content. Yes No

Add, modify, and delete JDBC datasources. Yes No

Modify HTTP and AJP connector settings. Yes No

Create and view general services. Yes No

Modify general engine configuration. Yes No

Pre-tuned JVM options. Yes 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 Yes No

Uncaught exception detection Yes No

Garbage collection metrics, including throughput and count

Yes No

SQL query time monitoring metrics. Yes No

Enhance response time monitoring metrics Yes No

Enhanced connection pool health metrics Yes No

Enhanced thread pool health metrics Yes No

Role-based customizable dashboard Yes Yes (via Hyperic) Automated inventory of application servers

and software resources

Yes Yes (via Hyperic)

Real-time metric collection and monitoring of tc Runtime, Tomcat, Apache Web server, Apache ActiveMQ, underlying JVM, operating system, and other resources

(19)

Diagnostics, Metrics, and Monitoring

Charting and graphing performance Yes Yes (via Hyperic) Advanced alerting: multi-conditional,

availability, event, and recovery alerts, group-based alerting, and escalation schemes.

Log file tracing, alerts on event levels Yes Yes (via Hyperic) Alerts based on configuration file updates Yes Yes (via Hyperic) Performance baselining for alert thresholds Yes Yes (via Hyperic)

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

Table 4.5. Centralized Operations and Management Feature Comparison

Centralized Operations and Management

Secure, distributed, JMX-based server management

Yes No

Create application server groups Yes Yes (via Hyperic)

Application server start/stop/restart from central console

List deployed applications and current status Yes No Application deploy/undeploy/reload/start/stop Yes No

Security and access/authorization control Yes Yes (via Hyperic) Scheduled control: maintenance activities,

on-demand actions, scheduled remediation actions, or scheduled responses to alert conditions

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. Yes No

Create server groups. Yes No

Add and delete servers to and from groups. Yes No List deployed applications, including current

status.

Yes No

Deploy application WAR file. Yes No

Undeploy application. Yes No

Start, stop, and reload deployed applications. Yes No Get (download) configuration files and JVM

parameters from a server.

Yes No

Modify configuration files on an individual server.

(20)

Scripting Features tc Runtime Apache Tomcat

Set (push) configuration files and JVM parameters to a server group.

Yes No

Start, stop, and restart a server or group of servers

(21)

5. 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 platform-neutral 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

(22)

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 platform-neutral 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:

(23)

2. 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 3.

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

(24)

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:

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 tcruntime-instance.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

(25)

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:

http://host:8080/insight

where host refers to the computer on which Spring Insight is running. If you are on the same computer, you can use localhost:

http://localhost:8080/insight

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.

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.

(26)

4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /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-2.6.0.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

(27)

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

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.

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

(28)

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.

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 platform-specific 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.X-EE.

(29)

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-serial-numbers.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-6.0.25.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 SSL-ready. 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.

(30)

• 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 6.0.30.A.RELEASE.

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

This directory contains the instance-specific files, such as the conf/server.xml file that configures this particular instance. If you created a tc Runtime instance called myserver and you are using the Standard Edition, then the

CATALINA_BASE of the instance is INSTALL_DIR/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:

(31)

• 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

(32)

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