Product Documentation. Pivotal tc Server. Version 3.x. Getting Started with Pivotal tc Server. Rev: Pivotal Software, Inc.

Transcription

1 Product Documentation Pivotal tc Server Version 3.x Rev: Pivotal Software, Inc.

2 Copyright Notice Copyright Copyright 2014 Pivotal Software, Inc. All rights reserved. Pivotal Software, Inc. believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." PIVOTAL SOFTWARE, INC. ("Pivotal") MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any Pivotal software described in this publication requires an applicable software license. All trademarks used herein are the property of Pivotal or their respective owners. 2

3 Copyright 3

4 Contents 4 Contents Preface: Contacting Pivotal...vi Current Pivotal Customers...vi Public Inquiries About Application Fabric Products...vi Chapter 1: About...8 Intended Audience...8 Quick Start...8 Overview of tc Server Usability Enhancements to Apache Tomcat Easy Monitoring with the VMware vcenter Hyperic Agent Plug-In Agile Application Development with Spring Insight Developer...11 Application Cluster Monitoring with Spring Insight Operations...11 tc Server Editions Migrating Java EE Applications to tc Server...13 Related Documentation Installing Pivotal tc Server...14 Install tc Server Standard Edition From a ZIP or TAR File...14 Mac OS X: Install Pivotal tc Server Developer Edition as a Homebrew Brew...15 RHEL: Install Pivotal tc Server Standard Edition from an RPM...16 Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package Repository...18 Windows: Install tc Server Standard or Developer Edition Using the MSI Installer Install Hyperic Agent Plugin Install tc Server Developer Edition From a ZIP or TAR File Overview of tc Server Directories, Variables, and Configuration Files...23 Enabling Bash Completion for tc Server Scripts...26 Setting Up Unix Users for tc Server and VMware vcenter Hyperic Uninstalling tc Server: Typical Steps Creating and Managing tc Runtime Instances...29 Create and Modify a tc Runtime Instance Manually Windows: Create and Modify tc Runtime Instances Starting and Stopping tc Runtime Instances Manually Deploy Applications to tc Runtime Instances...59 Embed tc Server...60 Security Information...63 External Interfaces, Ports, and Services...63 Resources That Must Be Protected Log File Locations User Accounts Created at Installation...64 Obtaining and Installing Security Updates Upgrade and Migration Guide...65 Upgrade an Instance with a Later tc Runtime Binary Upgrade an Instance in a New tc Server Directory Upgrade an Instance in the Existing tc Server Directory Run an ERS Tomcat Instance on tc Server Migrate an ERS Tomcat Instance to tc Server Tutorial: Very Simple HelloWorld Web Application...71 Before You Begin Creating and Deploying the HelloWorld Web Application... 71

5 Contents 5 Java Source of the Hello.java Servlet...73 JSP Source for the hello.jsp JSP...75 Sample web.xml File Sample Default index.html File Ant Build File to Compile and Package the Example Troubleshooting tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite...78 tc Runtime: JVM Performing a Full GC... 79

6 Contacting Pivotal Contacting Pivotal Current Pivotal Customers Submit a ticket from the Help & Support Page. Public Inquiries About Application Fabric Products the appropriate group for the Application Fabric product: [email protected] [email protected] [email protected] vi

7 Contacting Pivotal vii

8 About Chapter 1 About describes product concepts and provides setup instructions for Pivotal tc Server. Read the documentation to learn how to create, start, and stop tc Runtime instances; and deploy Web applications. Intended Audience This document is intended for anyone who wants to install, configure, and use tc Server to develop or to serve Web applications. Quick Start This section provides quick start instructions for installing Pivotal tc Server Standard Edition, creating a tc Runtime instance, and starting the tc Runtime instance. If you are upgrading an existing tc Server installation, see the upgrade documentation. If you are installing tc Server Developer Edition, see Install tc Server Developer Edition. Install tc Server Note: This section provides instructions for installing tc Server Standard Edition from a ZIP file. On a Windows machine, you could alternatively use the MSI installer. 1. Download and install a JDK or JRE on the computer on which you are installing tc Server. See Supported Configurations and System RequirementsSupported Configurations and System Requirements. 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 VMware vcenter 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/pivotal) if it doesn't already exist. Unix example: prompt$ mkdir /opt/pivotal Windows example: prompt> mkdir \opt\pivotal 8

9 About 5. From the Pivotal tc Server product page, click Downloads. 6. Download the most recent pivotal-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 release number, for example RELEASE. This is all that is required to install tc Runtime. For example, in Unix, if you specified a directory called /opt/pivotal in the preceding step and downloaded the Standard Edition file to your home directory: prompt$ cd /opt/pivotal prompt$ unzip ~/pivotal-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/pivotal/pivotal-tc-serverstandard-version. This directory contains all the tc Runtime files and directories. 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). Pivotal 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/pivotal/pivotal-tc-server-standard release prompt$./tcruntime-instance.sh create --instance-directory /var/opt/ pivotal/pivotal-tc-server-standard myserver Windows example: prompt> cd \opt\pivotal\pivotal-tc-server-standard release prompt> tcruntime-instance.bat create --instance-directory \var\opt\pivotaltc-server-standard myserver 2. Execute the tcruntime-ctl command to start the new tc Runtime instance; use the -i option to specify the directory in which the instance is located. Unix example: prompt$./tcruntime-ctl.sh myserver start -i /var/opt/pivotal/pivotal-tcserver-standard Windows example: prompt> tcruntime-ctl.bat myserver start -i \var\opt\pivotal\pivotal-tcserver-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 Read about additional options for creating tc Runtime Instances, such as automatically configuring a NIO HTTPS connector or using Elastic Memory for Java (EM4J) 9

10 About Overview of tc Server Pivotal 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 cloudready applications. With its lean architecture and small 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 Monitoring with the VMware vcenter Hyperic Agent Plug-In Agile Application Development with Spring Insight Developer Application Cluster Monitoring with Spring Insight Operations tc Server Editions Migrating Java EE Applications to tc Server 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. Easy Monitoring with the VMware vcenter Hyperic Agent Plug-In VMware vcenter Hyperic is a comprehensive enterprise application management tool. Two versions of the Hyperic Agent plugin are available: tc Runtime 8 Plugin Pivotal provides a new Hyperic Agent plugin for tc Runtime 8 to monitor your instances of Pivotal tc Server on any computer, all Spring-powered applications, and a variety of other platforms and application servers such as Apache Tomcat using VMware vcenter Hyperic Server. Hyperic provides a single console with powerful dashboards from which you can easily check the health of your applications. The capability to manage tc Server instances is not available. With Hyperic Server you can: Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting local or remote instances. 10

11 About In addition to the preceding tc Runtime-related actions, Hyperic performs these standard tasks: Inventories the resources on your network. Monitors your resources. Alerts you to problems with resources. Controls the resources. tc Runtime 7 (version 2.9.x) Plugin The legacy version 2.9.x Hyperic Agent plugin for tc Runtime 7 is also supported. This plugin provides management and monitoring capability. With Hyperic Server, you can: Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting local or remote instances. Similarly manage the lifecycle of a group of tc Runtime instances that are distributed over a network of computers. Configure a single instance of tc Runtime. Configuration options include the various port numbers to which the tc Runtime instance listens, JVM options such as heap size and enabling debugging, default server values for JSPs and static content, JDBC datasources, various tc Runtime connectors, and so on. Configure a group of tc Runtime instances using the tcsadmin command. Deploy a Web application from an accessible file system, either local or remote. You can deploy to both 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 instances. Application lifecycle operations include start, stop, redeploy, undeploy, and reload. In addition to the preceding tc Runtime-related actions, Hyperic performs these standard tasks: Inventories the resources on your network. Monitors your resources. Alerts you to problems with resources. Controls the resources. For detailed information on using the Hyper Agent plugin to manage your tc Server instances, see the VMware vcenter Hyperic documentation. 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. 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. 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 11

12 About 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. tc Server Editions tc Server is available in three different editions. tc Server Developer is geared towards the enterprise application developer. tc Server Standard and Spring Edition are designed for operators and administrators. Table 1: Pivotal tc Server Editions Feature Developer Edition Standard Edition Spring Edition tc Runtime x x x Spring Insight Developer VMware Hyperic with tc Server Plug-In x x Spring Insight Operations 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. x 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 About 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: pivotal-tc-server-developer-version.release.msi pivotal-tc-server-developer-version.release.tar.gz pivotal-tc-server-developer-version.release.zip 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 SSLenabled). This edition does not include Spring Insight Developer. x x 1 Only included when tc Server is purchased through VMware. 12

13 About With the Standard Edition, you have access to the vcenter Hyperic management system 1, which (as of version 4.6) includes the tc Server Hyperic plug-in in the general distribution. Install vcenter 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: pivotal-tc-server-standard-version.release.msi pivotal-tc-server-standard-version.release.tar.gz pivotal-tc-server-standard-version.release.zip Pivotal tc Server Standard Edition is also available as an RPM for customers installing on Red Hat Enterprise Linux (RHEL) and as a Debian package for customers installing on Ubuntu. To download an evaluation of Hyperic, go to the Pivotal Downloads Center. Spring Edition The tc Server Spring Edition includes all of the components and features of tc Standard Edition, plus Spring Insight Operations 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. The tc Server Spring Edition is the same binary distribution as the Standard Edition, with licensing differences. The Spring Insight Operations Dashboard template is a separate download at the Pivotal download center. From the Pivotal tc Server product page, click Downloads. Migrating Java EE Applications to tc Server If you have Java EE applications you would like to migrate from another runtime to tc Server, you can use the Spring Migration Analyzer command-line tool to generate migration analysis reports that contain information about the APIs the application uses, and any migration tasks that might be necessary to run the application on tc Runtime. You can download Spring Migration Analyzer from 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 7.0 Documentation Apache Tomcat 8.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 13

14 About Java Servlet Technology JavaServer Pages (JSP) Technology Installing Pivotal tc Server Installation options vary according to 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. Subtopics Install tc Server Standard Edition From a ZIP or TAR File Mac OS X: Install Pivotal tc Server Developer Edition as a Homebrew Brew on page 15 RHEL: Install tc Server Standard Edition From an RPM Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package Repository Windows: Install tc Server Standard or Developer Edition From the MSI Installer Install Hyperic Agent Plugin Install tc Server Developer Edition From a ZIP or TAR File Overview of tc Server Directories, Variables, and Configuration Enabling Bash Completion for tc Server Scripts Setting Up Unix Users for tc Server and Hyperic Install tc Server Standard Edition From a ZIP or TAR File Prerequisites Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements. Review information about tc Server Standard edition and its *.zip or *.tar.gz distribution files. See tc Server Editions. If you are installing from a *.tar.gz on a Solaris, make sure to use GNUtar to unpack the archive. 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. Attention: 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 Pivotal tc Server product page, click Downloads. 2. Download the Standard Edition package distribution in ZIP or compressed TAR format to a directory on your computer, for example /home/downloads. pivotal-tc-server-standard-version.release.zip pivotal-tc-server-standard-version.release.tar.gz 14

15 About 3. Log in 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. 4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /opt/pivotal. For example, on Unix: prompt$ mkdir /opt/pivotal 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/pivotal in the preceding step, and downloaded the Standard Edition ZIP file in the /home/downloads directory: prompt$ cd /opt/pivotal prompt$ unzip /home/downloads/pivotal-tc-server-standard release.zip This action creates a directory called pivotal-tc-server-standard-version 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 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 and starting tc Server components, see Creating and Managing tc Runtime Instances. Mac OS X: Install Pivotal tc Server Developer Edition as a Homebrew Brew You can install Pivotal tc Server Developer Edition on Mac OS X computers using Homebrew. Note: You may not be able to install the tc Server brew from inside a firewall. Install Pivotal tc Server Developer Edition Prerequisites Verify that your system meets the supported configurations described in Supported Configurations and System Requirements. Ensure that you have the latest brews. brew update Procedure 1. Log in to the Mac OS X computer on which you will install Pivotal tc Server. 2. Execute the following brew commands: brew tap pivotal/tap brew install tcserver What to do next For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files. 15

16 About For typical post-installation procedures such as creating tc Runtime instances and starting tc Server components, see Creating and Managing tc Runtime Instances. Run the following command to create a new tc Server instance in the current directory: tcruntime-instance.sh create <instance_name> Run the following command to create a new tc Server instance with Spring Insight monitoring: tcruntime-instance.sh create -t insight <instance_name> Run the following command to start a tc Server instance in current directory: tcruntime-ctl.sh <instance_name> start RHEL: Install Pivotal tc Server Standard Edition from an RPM Pivotal recommends that you install Pivotal tc Server (Standard Edition) on a Red Hat Linux Enterprise (RHEL) computer by first installing the Pivotal RPM repository and then using yum to perform the actual installation. See Install Pivotal tc Server from the Pivotal RPM Repository. You can also download the RPM from the Pivotal download page and install it on your RHEL computer using the rpm command, as described in Install Pivotal tc Server from a Downloaded RPM. Install Pivotal tc Server from the Pivotal RPM Repository Pivotal recommends that you install tc Server on RHEL computers using the Pivotal RPM repository. Prerequisites Set the JAVA_HOME environment variable in the root user's environment. For example, you could add the following line to /etc/profile and then open a new terminal window: export JAVA_HOME=/usr/java/latest Replace/usr/java/latest with the base directory of your JVM installation. Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements. Install the Pivotal repository RPM, which makes it easier for you to browse the Pivotal RPMs, including the Pivotal tc Server RPM. You install the Pivotal repository RPM on each RHEL computer on which you want to install one or more Pivotal products, such as Pivotal tc Server. 1. On the RHEL computer, start a terminal either as the root user or as an unprivileged user who has sudo privileges. 2. Install the Pivotal repository RPM using the following wget command, passing it the appropriate URL. Important: Run the entire wget command on a single line. Be sure you include the sh at the end, or the RPM installation fails. prompt# wget -q -O - sh Use sudo to run the preceding commands if you are not logged in as the root user. For example: prompt$ wget -q -O - sudo sh The command performs the following tasks: Imports the Pivotal GNU Privacy Guard (GPG) key. Installs the Pivotal repository RPM. Launches the Pivotal End User License Agreement (EULA) acceptance and repository configuration script. Outputs the EULA for you to read; you must answer yes to accept the terms and continue. 3. Use the yum search pivotal command to view the list of Pivotal components that you can install from the Pivotal repository. For example (output truncated for clarity): 16

17 About Procedure prompt# yum search pivotal... ======================================== Matched: pivotal ======================================== pivotal-rabbitmq-java-client-bin.noarch : The RabbitMQ Java Client Library pivotal-rabbitmq-server.x86_64 : The RabbitMQ server pivotal-tc-server-standard.noarch : Pivotal tc Server Standard pivotal-web-server.x86_64 : Pivotal Web Server... The Pivotal tc Server RPM is called pivotal-tc-server-standard. 1. From the RHEL computer on which you will install Pivotal tc Server, log in as the root user (or as an unprivileged user who has sudo privileges) and start a terminal. 2. Execute the following yum command: prompt# yum install pivotal-tc-server-standard The yum command begins the install process, resolves dependencies, and displays the packages it will install. If necessary, use sudo to run the preceding command if you are not logged in as the root user. For example: prompt$ sudo yum install pivotal-tc-server-standard 3. Enter y at the prompt to begin the actual installation. If the installation is successful, you see a Complete! message at the end. What the yum install command does The yum install command: Installs Pivotal tc Server into the /opt/pivotal/pivotal-tc-server-standard directory and sets the owner of the directory, along with all child directories and files, to root:pivotal. If the user does not already exist, adds a tcserver non-interactive user (in the group pivotal). Pivotal recommends that you create and run tc Server instances as this user. You cannot log in directly as the tcserver user because interactive login is disabled. Rather, you must log in as the root user or as a privileged user using sudo, and then su - tcserver. Creates an empty directory called /var/opt/pivotal/pivotal-tc-server-standard and sets the owner to tcserver:pivotal. Pivotal recommends that you create new tc Server instances in this directory rather than the installation directory. You do this by specifying the -i option of the tcruntime-instance command. What to do next 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 and starting tc Server components, see Creating and Managing tc Runtime Instances. Install Pivotal tc Server From a Downloaded RPM You can install Pivotal tc Server on RHEL by downloading the RPM from the Pivotal download center and executing the rpm command. 17

18 About Prerequisites Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements. Procedure 1. Log in to the RHEL computer on which you will install Pivotal tc Server as the root user (or as an unprivileged user who has sudo privileges). 2. From the Pivotal tc Server product page, click Downloads. 3. Download the tc Server Standard Edition RPM file to a directory on your computer. The RPM file is called pivotal-tc-server-standard-version-release.noarch.rpm. 4. Start a terminal and change to the directory in which you downloaded the RPM. 5. Execute the following rpm command to install tc Server: prompt# rpm -ivhf pivotal-tc-server-standard-version-release.noarch.rpm If necessary, use sudo to run the preceding command if you are not logged in as the root user. For example: prompt$ sudo rpm -ivhf pivotal-tc-server-standard-version- RELEASE.noarch.rpm 6. In the previous section, see What the yum install command does for post-installation information, such as the installation directory and the user that is automatically created by the RPM installation. (The yum install command corresponds to the rpm command in this procedure.) See What to do next for the suggested next steps. Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package Repository It is recommended that you install Pivotal tc Server (Standard Edition) on a computer running Ubuntu by first installing the Pivotal Debian package repository and then using apt-get to perform the tc Server installation. Prerequisites Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements. Install the Pivotal Debian package repository that contains the Pivotal tc Server *.deb packages. 1. On the Ubuntu computer, start a terminal either as the root user or as an unprivileged user who has sudo privileges. 2. Install the Pivotal Debian package repository using the following wget command: Important: Run the entire wget command on a single line. Be sure you include the sh at the end, or the installation fails. prompt# wget -q -O - sh If necessary, use sudo to run the preceding commands if you are not logged in as the root user. Use the following sudo command: prompt$ wget -q -O - packages.pivotal.io/ sudo sh The command performs the following tasks: Imports the Pivotal GNU Privacy Guard (GPG) key. Installs the Pivotal Debian package repository. Launches the Pivotal End User License Agreement (EULA) acceptance and repository configuration script. 18

19 About Outputs the EULA for you to read; you must answer yes to accept the terms and continue. 3. Use the apt-cache search pivotal command to view the list of Pivotal components that you can install from the Pivotal Debian package repository. For example: Procedure prompt# apt-cache search pivotal pivotal-tc-server-standard - Commercial Java application server based on Apache Tomcat pivotal-web-server - Pivotal Web Server pivotal-web-server-devel - Pivotal Web Server Libraries and Headers pivotal-repo-precise - Pivotal EULA and APT repo configuration utility From the Ubuntu computer on which you will install Pivotal tc Server, log in as the root user (or as an unprivileged user who has sudo privileges) and start a terminal. 2. Execute the following apt-get command: prompt# apt-get install pivotal-tc-server-standard The apt-get command begins the install process, resolves dependencies, and displays the packages it will install. If necessary, use sudo to run the preceding command if you are not logged in as the root user: prompt$ sudo apt-get install pivotal-tc-server-standard What the apt-get install command does The apt-get install command: Installs Pivotal tc Server into the /opt/pivotal/pivotal-tc-server-standard directory and sets the owner of the directory, along with all child directories and files, to root:pivotal. If the user does not already exist, adds a tcserver non-interactive user (in the group pivotal). It is recommended that you create and run tc Server instances as this user. You cannot log in directly as the tcserver user because interactive login is disabled. Rather, you must log in as the root user or as a privileged user using sudo, and then su - tcserver. Creates an empty directory called /var/opt/pivotal/pivotal-tc-server-standard and sets the owner to tcserver:pivotal. It is recommended that you create new tc Server instances in this directory rather than the installation directory. You do this by specifying the -i option of the tcruntime-instance command. What to do next 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 and starting tc Server components, see Creating and Managing tc Runtime Instances. Windows: Install tc Server Standard or Developer Edition Using the MSI Installer Prerequisites Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements. Review information about tc Server Standard Edition or Developer Edition. See tc Server Editions. For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user. 19

20 About Procedure 1. From the Pivotal tc Server product page, click Downloads. 2. Download the MSI installer distribution package for the Standard Edition or Developer Edition to a convenient directory on your computer. pivotal-tc-server-developer-version.release.msi pivotal-tc-server-standard-version.release.msi 3. Log in to the computer on which you are installing tc Server as the appropriate user, such as tcserver. 4. Navigate to the directory where you downloaded the distribution package. 5. Double-click the MSI installer. The Welcome page opens. 6. Click the Next button. The End-User License Agreement page opens. 7. Read the text. If you agree, then accept the terms. 8. Click the Next button. The setup type page opens. The page describes two setup types: Sample: All setup options are selected for you. This setup type is intended for potential customers who are evaluating the software. This option installs the tc Runtime to the default location and creates a sample instance called MyInstance with HTTP listening on port For more control over the installation choices, choose the Custom option instead. a. Click the Sample button. The setup options list page opens. b. Review the list. c. Click the Install button when you are ready to proceed. Custom: You can select all of the setup options. a. Click the Custom button. The Custom Setup page opens. b. Choose to accept the default installation location for the application files, or browse and select a different location on your local hard drive. c. Click the Next button. The Create Instance page opens. Complete the following fields: Enter a logical name for the instance. Select the Apache Tomcat version to install. Select the Use Instance configuration file checkbox if you want to configure your new tc Runtime instance using a properties file. Configuration File: Browse to and select the location of the file containing properties that you want to apply to the new tc Runtime instance. When you create a 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 tcruntimeinstance script on the command line rather than accepting the default values, create a file with values such as the following: bio.http.port=

21 About bio.https.port=9191 Post-installation, see the configuration-prompt.properties file in the INSTALL_DIR/ pivotal-tc-server-edition-release/templates/template-name directory for the list of configuration properties that apply to a particular template. Instance Location: Accept the default instance location, or browse to and select a new location. JAVA_HOME: Accept the default Java runtime engine location, or browse to and select a different JRE directory. d. Click the Next button. A page listing available templates opens. Select from among the available templates to apply to your tc Runtime instance. You can apply multiple templates to the instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files copied to the instance. For additional details and examples about using templates, see Templates Provided by tc Server on page 46. e. Click the Next button. The setup options list page opens. f. Review the list. g. Click the Install button when you are ready to proceed. 9. The setup wizard: Installs tc Server Creates the initial tc Runtime instance Configures and starts the Microsoft Windows services. What to do next For typical post-installation procedures such as creating tc Runtime instances and starting tc Server components, see Creating and Managing tc Runtime Instances. Uninstalling tc Server The following options are available to uninstall tc Server: Click the Start button > All Programs > Pivotal > Uninstall Pivotal tc Server. Uninstall Pivotal tc Server using the Programs control panel. You can optionally remove all tc Runtime instances when you uninstall the application. Install Hyperic Agent Plugin Two versions of the Hyperic Agent plugin are available: tc Runtime 8 Plugin 1. Download the Pivotal tc Server plugin from the Pivotal Network. 2. Rename the plugin file pivotal-tcserver-plugin.jar. 3. Install the plugin using the Hyperic Plugin Manager. For instructions, see "Deploying and Managing Plug-ins" in the VMware vcenter Hyperic documentation. 21

22 About tc Runtime 7 Plugin 1. Download the Pivotal tc Server plug-in 2.9.x for VMware Hyperic from Pivotal Network. 2. Complete the installation using the instructions found in the README file. The README is located inside the plugin zip archive. Install tc Server Developer Edition From a ZIP or TAR File When you install the Developer Edition of tc Server, you also typically 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 supported configurations and installation requirements. See Supported Configurations and System Requirements. Review information about tc Server Developer edition and its *.zip or *.tar.gz distribution files. See tc Server Editions. If you are installing from a *.tar.gz on a Solaris, make sure to use GNU tar to unpack the archive. 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. Attention: 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 Pivotal tc Server product page, click Downloads. 2. Download the Developer Edition distribution in ZIP or compressed TAR file format. pivotal-tc-server-developer-version.release.zip pivotal-tc-server-developer-version.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. 4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /opt/pivotal. For example, on Unix: prompt$ mkdir /opt/pivotal 5. Extract the tc Server distribution file into the new directory. This action creates a directory called pivotal-tc-server-developer-version 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. 6. Create a tc Runtime instance that contains Spring Insight by specifying the insight template. Unix: Change to the /opt/pivotal/pivotal-tc-server-developer-version directory and execute the tcruntime-instance.sh script to create an instance. 22

23 About Pivotal 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/pivotal/pivotal-tc-server-developer release prompt$./tcruntime-instance.sh create -t insight -i /var/opt/pivotal/pivotal-tc-server-developer insight-instance Windows: Change to the \opt\pivotal\pivotal-tc-server-developer-version directory and execute the tcruntime-instance.bat script to create an instance: prompt> cd \opt\pivotal\pivotal-tc-server-developer release prompt> tcruntime-instance.bat create -t insight -i \var\opt\pivotal\pivotal-tc-server-developer insight-instance 7. Start the new tc Runtime instance. Unix: Execute the tcruntime-ctl.sh script to start the instance; use the -i option to specify the directory in which the instance is located. For example: prompt$./tcruntime-ctl.sh insight-instance start -i /var/opt/pivotal/ pivotal-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 -i option to specify the directory in which the instance is located: prompt> tcruntime-ctl.bat insight-instance install -i \var\opt\pivotal \pivotal-tc-server-developer prompt> tcruntime-ctl.bat insight-instance start -i \var\opt\pivotal \pivotal-tc-server-developer Note: On Windows, Pivotal 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 Pivotal tc Runtime instance - unique-name, where unique-name is a unique combination of server name and server directory. 8. 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. 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 pivotal-tc-server-edition-version subdirectory, where edition-version refers to the edition of tc Server that you are using (standard or developer) and the version of tc Server. This subdirectory in turn contains the following tc Serverrelated files and directories: 23

24 About 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 or tomcat a.release. These directories are 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 clusternode 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. See Templates Provided by tc Runtime for the full list. 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 creates the instance directory specified with the -i option or, by default, a subdirectory of the pivotal-tc-server-editionversion 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/pivotal-tcserver-edition-version/tomcat-version, where INSTALL_DIR is the directory in which you installed tc Server (such as /opt/pivotal); edition-version refers to the version and edition of tc Server you are using (developer release or standard release); 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/pivotal-tc-serverstandard-version/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/ pivotal/tcserver/tcruntime-instance-6.log, set the variable in your environment or setenv.sh as follows: CATALINA_OUT=/opt/pivotal/tcserver/tcruntime-instance-6.log 24

25 About INSTANCE_NAME. Name of the tc Runtime instance. You can use this variable to create other unique variables within configuration scripts. For example, on Unix platforms you can update the bin/setenv.sh file to use the name of the tc Runtime instance when defining the CATALINA_OPTS variable as follows: CATALINA_OPTS="-Dinstance.name=$INSTANCE_NAME" On Windows, the equivalent change would be to the conf/wrapper.conf file as follows: set CATALINA_OPTS=-Dinstance.name=%INSTANCE_NAME% INSTANCE_BASE. Specifies the parent directory of the tc Runtime instance. The full pathname of the tc Runtime instance directory would be $INSTANCE_BASE/$INSTANCE_NAME. You can use the INSTANCE_BASE variable in the same way as the INSTANCE_NAME variable, as described in the preceding bullet. tc Runtime Instance Directory Structure After you create a new tc Runtime instance, its CATALINA_BASE directory contains the following 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. 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. The default JMX user, added at instance creation time unless you specify something different, is called admin with a password made up of a list of random characters. 25

26 About 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 tcruntimectl.sh scripts. When enabled, you can 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/pivotal/tcserver/pivotal-tc-serverstandard 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 VMware vcenter Hyperic On Unix-like systems, the interaction between VMware vcenter Hyperic and tc Server is straightforward as long as tc Runtime instances and the Hyperic Agent run as the same user. You can 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 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. Both Hyperic Agent and tc Runtime instances should run as regular, non-root users. Never 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. Subtopics Creating Users and Groups for Hyperic and tc Server 26

27 About Setting the tc Server User in Hyperic Enabling Hyperic Agent Access to su or sudo 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 pivotal group: prompt$ groupadd pivotal Note that if you installed from RPM on RHEL or from a Debian package on Ubuntu, the pivotal group may already exist. 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 pivotal group: prompt$ useradd hyperic -g pivotal 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 pivotal group: prompt$ useradd tcserver -g pivotal 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 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. 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 27

28 About 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 tcruntime-ctl.sh script is in /opt/pivotal/ pivotal-tc-server-standard release/tcruntime-ctl.sh, you would add the following entry to /etc/sudoers: hyperic ALL=(tcserver) NOPASSWD: /opt/pivotal/pivotal-tc-serverstandard release/tcruntime-ctl.sh Uninstalling tc Server: Typical Steps You can uninstall one or more of the following components: 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 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. Remove the directory in which you installed the Hyperic Agent. For example: prompt$ cd /opt/vmware/hyperic prompt$ rm -rf <version> Uninstalling tc Runtime The following procedure describes how to uninstall the tc Runtime and all its associated instances. 28

29 About 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\pivotal\pivotal-tcserver-standard\myserver\bin) and uninstall the service using the following command: prompt> \var\opt\pivotal\pivotal-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/pivotal/pivotal-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. Creating and Managing tc Runtime Instances After you install Pivotal tc Server components on all relevant computers, you perform some or all of the following post-installation tasks, depending on the edition of tc Server. (As a performance-monitoring alternative to VMware vcenter Hyperic, you can install and configure Spring Insight. See the Spring Insight Operations documentation.) Subtopics Create and Modify a tc Runtime Instance Manually Windows: Create and Modify tc Runtime Instances Start and Stop tc Runtime Instances Manually Deploy Applications to tc Runtime Instances Embed tc Server Create and Modify a tc Runtime Instance Manually The following sections describe how to create new instances of tc Runtime and provide related information: Create tc Runtime Instances with the tcruntime-instance Command Script tcruntime-instance.sh Reference Create Evaluation Instances with the createinstance Script Pin tc Runtime Instances to a Specific Version Best Practice: Naming tc Runtime Instances Differences Between the Separate and Combined Layouts Using the tc Runtime Templates Templates Provided by tc Runtime Additional Information About Using the SSL Templates 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 (\). 29

30 About Creating tc Runtime Instances with the tcruntime-instance Command Script This section describes the simplest way to use the tcruntime-instance command script 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. On the computer on which you installed tc Server, log in as the user who will run tc Runtime instances, such as tcserver. On Unix, if you have disabled interactive login, log in as the root user and use su - tcserver to become the user. 2. Be sure you have installed a JDK or JRE and have set your JAVA_HOME and PATH environment variables correctly. See Software Requirement: Install JDK or JRE. 3. Open a terminal window (Unix) or Command Prompt (Windows). 4. Change to the INSTALL_DIR/pivotal-tc-server-edition -release directory, where INSTALL_DIR refers to the main tc Server installation directory, such as /opt/pivotal, 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/pivotal/pivotal-tc-server-standard release 5. 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. Pivotal 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/pivotal/pivotal-tcserver-standard myserver On Windows: prompt> tcruntime-instance.bat create -i \var\opt\pivotal\pivotal-tc-serverstandard myserver When the preceding sample command completes, the new tc Runtime instance is located in the /var/ opt/pivotal/pivotal-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 either the Java binaries pointed to by your JAVA_HOME environment variable or the java binary that it found in the PATH environment variable when it started. You can hard-code Java binaries that the tc Runtime instance uses by 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 change the version to which the instance is pinned. 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. 30

31 About tcruntime-instance.sh Reference You can use the tcruntime-instance command script to create, modify, and upgrade a tc Runtime instance; list existing instances; and display help for the command script. Each command has its own set of options, as described in the tables in this section. Depending on the command, you must specify the name of a tc Runtime instance. The general syntax for each of the commands follows; click on the link to see the options for that particular command: tcruntime-instance create [options] instance-name tcruntime-instance create instance-property-file tcruntime-instance apply-template [options] instance-name tcruntime-instance modify-version [options] instance-name tcruntime-instance upgrade [options] instance-name tcruntime-instance list [options] tcruntime-instance help [command-name] create Command Use the create command to create a new tc Runtime instance. The create command accepts a number of options for customizing the instance. You can specify these options at the command line or list the options in a file and specify the name of the file after the create command. 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. To configure different or additional features using the templates, such as the NIO Connector, clustering, or SSL, use the --template option to specify the appropriate template; you must use the option for each template you want to apply. Pivotal 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 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. 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. You can also specify these options in a file and pass the name of the file as a parameter to the create command; see the examples. Table 2: Options of the create Command Option (Long Form) Option (Short Form, if available) Description --force N/A Forces the script to create a new tc Runtime instance, even if one already exists. By default the script does not force the creation. 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 31

32 About Option (Long Form) Option (Short Form, if available) Description 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. Also use this parameter to change the default SSL configuration values when using the - t option to specify an SSL template, such - t bio-ssl. 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. --layout layout N/A Specifies the type of layout you want your new tc Runtime instance to use: separate or combined. The default value is separate. In the separate layout, CATALINA_HOME and CATALINA_BASE point to different directories; in the combined layout they point to the same directory, which means that the tc Runtime binaries are bundled within your instance. The combined is the standard Apache Tomcat layout. 32

33 About Option (Long Form) Option (Short Form, if available) Description Warning: Pivotal recommends that you always use the separate layout, which is why it is the default value if you do not specify this option. For additional 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.propertyname=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-propertyfile See the configurationprompt.properties file in the INSTALL_DIR/pivotal-tcserver-edition-release/ templates/template-name directory for the list of configuration properties that apply to a particular template. --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 two configuration properties: http.port and https.port. Other templates might specify their own 33

34 About Option (Long Form) Option (Short Form, if available) Description 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=9090 See the configurationprompt.properties file in the INSTALL_DIR/pivotal-tcserver-edition-release/ templates/template-name directory for the list of configuration properties that apply to a particular template. --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. Replace the template_name argument with the name of an existing subdirectory of the INSTALL_DIR/pivotal-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. 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 <Connector> element, then the script does not add a BIO Connector. For additional details and examples about using templates, see Using the tc Runtime Templates. 34

35 About Option (Long Form) Option (Short Form, if available) Description --version version -v version Pins the instance to the specified version of tc Runtime, such as A.RELEASE. 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 pinned to the highest version of tc Runtime it can find. For example, if A.RELEASE, B.RELEASE and A.RELEASE are all present, and you don't specify this option, then the script automatically chooses A.RELEASE as the version of the instance. See Pinning a tc Runtime Instance to a Specific Version for more information. The following example shows how to be prompted interactively for configuration properties (such as port numbers) and that you want the new tc Runtime instance to be located in the /var/opt/pivotal/ pivotal-tc-server-standard directory: prompt$./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-serverstandard --interactive myserver The following example shows how to pin a new instance to version A.RELEASE of tc Runtime and to specify a hard-coded value for JAVA_HOME: prompt$./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-serverstandard \ --version A.RELEASE --java-home /var/opt/java/jdk1.7.0_42 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/pivotal/pivotal-tc-server-standard myserver Creating an Instance From a File You can also specify most of the options in the previous table in a file and pass the file to the create command if you prefer not to specify the commands at the command-line. The following shows an example of such a file: instance-name=myserver force=true instance-directory=/var/opt/pivotal/pivotal-tc-server-standard java-home=/var/opt/java/jdk1.7.0_42 version= b.release layout=combined 35

36 About template.1=bio template.2=bio-ssl template.3=async-logger property.1=bio.http.port=9090 property.2=bio.https.port=9191 You can specify multiple templates or properties by using the form template.number or property.number. If you include multiple templates, they are applied in the specified order. Assume that the preceding file is called /var/opt/pivotal/properties/my-instance.txt, then you would create an instance with these properties using the following command: prompt$./tcruntime-instance.sh create /var/opt/pivotal/properties/myinstance.txt The apply-template Command Use the apply-template command to apply a new template to an existing tc Runtime instance. For example, assume you created and are using a tc Runtime instance to which you originally applied only the default template. You now want to start using the Elastic Memory for Java (EM4J) feature to optimize Java memory utilization on the instance while you run it on VMware ESXi. The EM4J feature is enabled through the elastic-memory template, so you use the apply-template command of the tcruntimeinstance.sh script to apply the new template, elastic-memory, to the existing instance. Refer to the README.txt file in the instance directory for the list of templates that have already been applied to the instance. For a list and description of all templates, see Templates Provided by tc Runtime. By default, you cannot apply the same template twice to an instance. You can override this default behavior by specifying the --override-duplicate-template option. The next table lists options for the apply-template command of tcruntime-instance.sh bat. Following the table is an example that applies a new template to an existing tc Runtime instance. With most options, you can use either the short form (such as -i) or the long form (such as --instancedirectory). Table 3: Options of the apply-template Command Option (Long Form) Option (Short Form, if available) Description --help -h Outputs usage information for applytemplate. --interactive N/A Tells the script to interactively ask for template-specific configuration properties. For example, use this parameter if you are applying a bio-ssl template and want to interactively change the default SSL configuration values. --instance-directory instancedir -i instancedir If the tc Runtime instance to which you are applying a new template is not in the default location (current working directory), use this option to specify the full or relative pathname of the directory of the instance. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntimeinstance.sh bat script. 36

37 About Option (Long Form) --override-duplicatetemplate Option (Short Form, if available) N/A Description The default value of this option is the current working directory. Allows you to apply the same template to an instance multiple times. --properties-file file -f file Specifies the name of a properties file that contains template-specific configuration properties that you want to apply to the existing tc Runtime instance. When you create the properties file, it should contain one property per line, in the form template-name.propertyname=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-propertyfile For the list of configuration properties that apply to a particular template, see the configuration-prompt.properties file in the INSTALL_DIR/pivotaltc-server-edition-release/ templates/template-name directory. --property templatename.propertyname=value -p templatename.propertyname=value Specifies a single configuration property that you want to apply to the existing tc Runtime instance. When you create a tc Runtime instance, the tcruntime-instance script always applies a template, even if it is the default one (called bio). Templates usually have configuration properties. For example, the bio template has two configuration properties: http.port and https.port. Other templates might specify their own configuration properties. If you want to pass your own values of these properties 37

38 About Option (Long Form) Option (Short Form, if available) Description 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=9090 For the list of configuration properties that apply to a particular template, see the configuration-prompt.properties file in the INSTALL_DIR/pivotaltc-server-edition-release/ templates/template-name directory.. --template template_name -t template_name Specifies the template you want to apply to the existing tc Runtime instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files that the tcruntime-instance script copies to or merges with the instance it just created. Replace the template_name argument with the name of an existing subdirectory of the INSTALL_DIR/pivotal-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. You can specify this option only once. If you want to apply multiple new templates to an existing tc Runtime instance, you must run the tcruntime-instance script multiple times. For additional details and examples about using templates, see Using the tc Runtime Templates. The following example shows how to apply the diagnostics template to an existing tc Runtime instance call myserver that is located in the /var/opt/pivotal/pivotal-tc-standard directory: prompt$./tcruntime-instance.sh apply-template -i /var/opt/pivotal/pivotal-tcserver-standard -t diagnostics 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. 38

39 About 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 7.0.X to 8.0.X. You can use it only to modify the version within a certain major release, such as A to A. Use the --version option to specify the new version of the instance. If you do not specify --version, the resulting instance is pinned to 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 for 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 4: 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. 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 pinned to the highest version of tc Runtime it can find. 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. 39

40 About Option (Long Form) Option (Short Form) Description --help -h Outputs usage information about the modify-version 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/pivotal/pivotal-tc-server-instances myotherserver In the preceding example, the myotherserver is located in the /var/opt/pivotal/pivotal-tcserver-instances directory. 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 modifyversion command changes the tc Runtime version to a tc Runtime based on a different Apache Tomcat release. 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 instance 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 5: 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 tcruntime-instance.sh bat script. 40

41 About Option (Long Form) Option (Short Form) Description The default value of this option is the current working directory. --version version -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 release is used; if the instance is currently using tc Runtime 7, it is upgraded to use the highest tc Runtime 7 version in the tc Server installation directory. Valid values for version depend on the versions of tc Runtime that you have installed. The tcruntimeinstance.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/pivotal/pivotal-tc-server-standard/ myinstance to a new instance at /opt/pivotal/pivotal-tc-server-standard-new/ myinstance. The upgraded instance will use tc Runtime release A.RELEASE. The command is executed in the /opt/pivotal/pivotal-tc-server-standard-new directory: prompt$ /opt/pivotal-tc-server-standard-new/tcruntime-instance.sh upgrade -v A.RELEASE -i /var/opt/pivotal/new-instances/ /var/opt/pivotal/ instances/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: 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 41

42 About Option (Long Form) Option (Short Form) Description directory from which you are running the tcruntime-instance.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/pivotal/pivotal-tc-serverstandard Listing instances in '/var/opt/pivotal/pivotal-tc-server-standard' myinstance Info: Instance name: myinstance Runtime version: A.RELEASE tc Runtime Base: myinstance Status: /var/opt/pivotal/pivotal-tc-server-standard/ 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 Create Evaluation Instances with the createinstance Script Use the quickstart/createinstance.sh bat interactive script to quickly create a simple SSLenabled tc Runtime instance. The script prompts you for all the information it needs. Note: The createinstance script is meant for users who want to quickly create a simple tc Runtime instance for evaluation purposes. You should use the tcruntime-instance script to create instances for production use. The createinstance.sh bat script uses the following two tc Server templates when it creates the instance: bio : Configures a Blocking IO (BIO) HTTP Connector. bio-ssl : Configures a Blocking IO (BIO) HTTPS Connector. If you want to create an instance using different templates, use the tcruntime-instance.sh bat script, as described in Creating tc Runtime Instances with the tcruntime-instance Command Script. 42

43 About Prerequisites The createinstance script automatically discovers a Java installation. If, however, you want to use a specific version of Java, then you must set the JAVA_HOME variable in your environment appropriately and update your PATH to include JAVA_HOME/bin. Procedure 1. On the computer on which you installed tc Server, log in 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/quickstart directory, where INSTALL_DIR refers to the main tc Server installation directory, and execute the createinstance.sh script (createinstance.bat on Window.) For example, on Unix: prompt$ cd /opt/pivotal/pivotal-tc-server-standard release/quickstart prompt$./createinstance.sh The script prompts you for information such as the home directory and name of the tc Runtime instance; whether to immediately start it; and the HTTP, HTTPS, and JMX ports to which the tc Runtime instance will listen. Pivotal recommends that you specify an instance directory different from the tc Server installation directory, such as /var/opt/pivotal/pivotal-tc-server-standard. The script also asks whether you want to generate a new keystore or whether you want to use an existing one. If you specify the former, the script prompts your for additional information about the key and keystore, such as the size of the SSL private key, the passwords of the private key and keystore itself, the location of the keystore, and identification data for the SSL certificate. After the script finishes prompting for information, it starts the instance (if you answered Yes to the prompt to immediately start it) and then exits. 4. If you answered Yes to the prompt to start the tc Runtime instance, confirm that the instance is running by invoking 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) and port is the HTTP port you specified (default 8080). For example: If you answered No to the prompt to start the instance, execute the tcruntime-ctl.sh bat command, specifying the name and location of the instance. For example, if you named the instance myserver and specified its instance directory /var/opt/pivotal/pivotal-tc-serverstandard: prompt$./tcruntime-ctl.sh myserver start -i /var/opt/pivotal/pivotal-tcserver-standard Pinning tc Runtime Instances to a Specific Version You can use the --version parameter of tcruntime-instance.sh bat to specify the version of tc Runtime to which the new instance is pinned. 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 when you create the instance, it is automatically pinned to the highest version available. 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 \ 43

44 About -i /var/opt/pivotal/pivotal-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/pivotal/pivotal-tc-serverstandard myserver the myserver instance is automatically pinned to the highest version available. Not having to explicitly specify a version when you create the instance is useful if you know that you simply want to use the highest available. To determine the tc Runtime version to which existing instance is pinned, check the file INSTANCE-DIR/ conf/tomcat.version which lists the version, such as A.RELEASE. When the instance starts, if it cannot find the tc Runtime version specified in its tomcat.version file, the instance outputs a warning and instead uses the highest version of tc Runtime in the same major runtime release (i.e. tc Runtime 7 or 8). For example, if the tomcat.version file specifies A.RELEASE, but the instance finds only the B.RELEASE and B.RELEASE versions, then the instance uses the B.RELEASE tc Runtime version. Note that it does not use any tc Runtime 8 release, if found, because this is a different major release. 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/pivotal/pivotal-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/pivotal/ pivotal-tc-server-standard/myserver directory, then its name is myserver. It is best practice to use unique names for the main installation directory for each tc Runtime instance on the same computer. Differences Between the Separate and Combined Layouts You can create two flavors of tc Runtime instances, depending on the layout of their files: 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-8.0.x.release directory, which in turn contains the set of tc Runtime binaries that are shared by other instances that use the separate layout. Pivotal 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. Pivotal 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. Using the tc Runtime Templates 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- 44

45 About 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. Templates make it easier to automatically configure certain tc Runtime features when you create a new tc Runtime instance or after you have already created it. These features include SSL, clustering, and so on. Creating a Runtime Instance with the tc Runtime Templates When you create a new tc Runtime instance, you use the --template option to specify a template to the tcruntime-instance create command, or to the tcruntime-instance apply-template command if you want to apply a template to an existing tc Runtime instance. When creating a new instance, you can specify the --template option multiple times if you want to apply multiple templates, such as clustering and SSL. When applying a template to an existing instance, you can specify the -- template only once per script execution. To use this feature, the specified template must already exist. You can use one of the out-of-the-box templates or one that you create yourselfcreate yourself. See Administration. The argument to the --template option of the tcruntime-instance script must be the tc Runtime template directory. The tcruntime-instance script looks for the template directory in the INSTALL_DIR/pivotal-tc-server-edition-version/templates directory, where editionversion refers to the edition of tc Server you are using (developer or standard) and the version of tc Server. 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/pivotal/ pivotal-tc-server-standard myserver In the preceding example, because it does not specify the --version or --java-home options, the instance is uses the latest installed version of tc Runtime, and the instance uses the value of JAVA_HOME in the environment. The instance is created in the /var/opt/pivotal/pivotal-tc-serverstandard/myserver directory. 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/pivotal/pivotal-tc-server-standard myserver Note that the insight template is available only in the Developer Edition of tc Server. What the tcruntime-instance Script Does to Create a Runtime Instance 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 VMware Hyperic. If you specified one or more templates with the --template option, the script applies each template in order. First the script copies over any non-configuration files (such as JAR files) to the appropriate instance directory, and then the script merges the configuration file fragments with the instance configuration files. You 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. 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 tcruntime-instance script adds a Blocking IO (BIO) HTTP Connector to the instance. Creates a README.txt file in the instance directory that lists the templates that have been applied to the instance. 45

46 About When you apply a template to an existing instance, the script applies the configuration properties and updates the README.txt appropriately. Template Directory Structure 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 serverfragment.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. Templates Provided by tc Server tc Server provides several 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. 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/pivotal/ pivotal-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/pivotal-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (developer or standard). Table 7: Out-of-the-Box Templates Provided by tc Runtime Template Name base ajp Comparison with Default tc Runtime Instance 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 VMware vcenter Hyperic. When this template is applied, either the base-tomcat-7 or base-tomcat-8 is applied as well, depending on the tc Runtime version to be used by the instance. Adds an Apache JServer 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 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. 46

47 About Template Name Comparison with Default tc Runtime Instance For more information, see Apache Portable Runtime (APR) based Native library for Tomcat on the Apache Tomcat Web site. apr-ssl Adds an APRLifecycleListener to detect the APR-based native library required to use the APR/native connector. Adds an APR HTTPS connector. Generates a self-signed certificate and public key file, located by default in the conf directory. Disables SSLv2 support. The available ciphers are limited to those allowed by Pivotal. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Additional Information About Using the SSL Templates. For general information about APR and SSL, see Apache Portable Runtime (APR) based Native library for Tomcat and SSL Configuration HOW-TO on the Apache Tomcat Web site. async-logger bio Configures asynchronous logging for the instance, which means that two separate tc Runtime threads handle incoming requests and write to the log file; by default, the same tc Runtime thread performs both actions. When you specify this template, the conf/logging.properties file contains references to the AsyncFileHandler class rather than the default FileHandler class. After you specify asynchronous logging for an instance, you can configure its behavior by setting certain system properties in the CATALINA_BASE/ bin/setenv.sh (Unix) or CATALINA_BASE/bin/setenv.bat (Windows) file. See the Configuring Asynchronous Logging section of the tc Server Administration Guide for details. Adds a Blocking IO (BIO) HTTP Connector to the new instance's server.xml file. bio-ssl Adds a Blocking IO (BIO) HTTPS connector. Generates a keystore that contains a self-signed certificate and a public key, and stores it in the conf directory by default. Disables SSLv2 support. The available ciphers are limited to those allowed by Pivotal. For more information, see Additional Information About Using the SSL Templates. For general information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site. cluster-node 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. 47

48 About Template Name Comparison with Default tc Runtime Instance 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. 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 clusternode.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 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 automatically adds a Blocking IO (BIO) HTTP Connector. gemfire-cs gemfire-p2p insight Provides fast, scalable, and reliable HTTP session replication for your tc Runtime instances, including support for the latest tc Runtime 8. This template applies to the client/server configuration of Pivotal GemFire. Provides fast, scalable, and reliable HTTP session replication for your tc Runtime instances, including support for the latest tc Runtime 8. This template applies to the point-to-point configuration of Pivotal GemFire. Developer Edition Only. 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 automatically adds 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 Updates the JmxSocketListener to use SSL for all JMX communication Generates a keystore that contains a self-signed certificate and a public key, and stores it in the conf directory by default. Disables SSLv2 support. The available ciphers are limited to those allowed by Pivotal. 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. 48

49 About Template Name Comparison with Default tc Runtime Instance For more information, see Additional Information About Using the SSL Templates. For general information, see SSL Configuration HOW-TO on the Apache Tomcat Web site. nio Adds a Non-Blocking IO (NIO) connector for HTTP. For more information, see The HTTP Connector on the Apache Tomcat Web site. nio-ssl Adds an NIO HTTPS connector. Generates a keystore that contains a self-signed certificate and a public key, and stores it in the conf directory by default. Disables SSLv2 support. The available ciphers are limited to those allowed by Pivotal. For more information, see Additional Information About Using the SSL Templates. For general information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site. redis-session-manager redis-session-managerauth Enables you to configure tc Runtime instances to use a Redis server for session management and replication. Does not require a user to specify a password to connect to Redis. Enables you to configure tc Runtime instances to use a Redis server for session management and replication. Requires a user to specify a password to connect to Redis. Additional Information About Using the SSL Templates If you specify one of the SSL templates (bio-ssl, nio-ssl, apr-ssl, or jmx-ssl) when you create a tc Runtime instance, the tcruntime-instance script automatically configures SSL or OpenSSL for the instance; generates a new keystore; and provides default values for various properties if you do not specify them interactively. For example, assume that you used the following command to create an instance: prompt$./tcruntime-instance.sh create myserver-secure -t bio-ssl -i /var/opt/ pivotal/pivotal-tc-server-standard The myserver-secure instance has the following default SSL properties and configuration: A generated keystore, located in the conf directory, with the name tc-server-bio-ssl.keystore. This keystore contains a self-signed certificate with default values (such as Unknown) for the organization information. Key alias named tc-server-bio-ssl. Key password consisting of a random string of characters. Keystore password that is the same as the key password HTTPS port of This default configuration is adequate for testing. Typically, when you move to a production environment, you want to generate keystores with real information about your organization and customize the passwords. In this case, use the --interactive option of tcruntime-instance.sh bat so that the script prompts you for the information about your particular environment. 49

50 About The --interactive option still generates a self-signed certificate. If you require an authentic, verified certificate, purchase one from a well-known Certificate Authority such as VeriSign, and use the keytool JDK tool to import the certificate into your keystore. See the Creating a Simple Keystore File For Both SSL and OpenSSL section in the Pivotal tc Server Administration Guide in this Documentation Center for more information. Windows: Create and Modify tc Runtime Instances The MSI installer for Microsoft Windows installs the Pivotal tc Server Configurator with the application. Creating a tc Runtime Instance 1. Click the Start button > All Programs > Pivotal > Pivotal tc Server Configurator. The application opens and displays the list of existing tc Runtime instances. 2. Click the Add button. The Create Instance window opens. 3. Complete the following fields: Enter a logical name for the instance. Select the Apache Tomcat version to install. Select the Use Instance configuration file checkbox if you want to configure your new tc Runtime instance using a properties file. Browse to and select the location of the file containing properties that you want to apply to the new tc Runtime instance. When you create a properties file, it should contain one property per line, in the form templatename.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 See the configuration-prompt.properties file in the INSTALL_DIR/pivotal-tcserver-edition-release/templates/template-name directory for the list of configuration properties that apply to a particular template. Accept the default instance location, or browse to and select a new location. 4. Click the Next button. The list of available templates page opens. Select from among the available templates to apply to your tc Runtime instance. You can apply multiple templates to the instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files copied to the instance. For additional details and examples about using templates, see Templates Provided by tc Server on page Click the Next button. The Ready to Create Instance page opens. 6. Review the list of instance setup options. 7. Click the Finish button when you are ready to proceed. Note: The configurator does not display a progress bar as it creates the new instance. 50

51 About The configurator displays the new tc Runtime instance in the list. 8. Click the Install button to create a Windows service for the instance. Starting and Stopping a tc Runtime Instance 1. Click the Start button > All Programs > Pivotal > Pivotal tc Server Configurator. The application opens and displays the list of existing tc Runtime instances. 2. Select the instance that you want to start or stop. 3. Start or stop the instance. Click the Start button to start the Windows service for the instance. Click the Stop button to stop the Windows service for the instance. Adding Templates to a tc Runtime Instance 1. Click the Start button > All Programs > Pivotal > Pivotal tc Server Configurator. The application opens and displays the list of existing tc Runtime instances. 2. Click the Add Templates button. The Add Templates to Instance window opens. 3. Select the instance that you want to modify. 4. Select the Use Instance configuration file checkbox if you want to configure your new tc Runtime instance using a properties file. Browse to and select the location of the file containing properties that you want to apply to the new tc Runtime instance. When you create a properties file, it should contain one property per line, in the form templatename.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 See the configuration-prompt.properties file in the INSTALL_DIR/pivotal-tcserver-edition-release/templates/template-name directory for the list of configuration properties that apply to a particular template. 5. Click the Next button. The list of available templates page opens. Select from among the available templates to apply to your tc Runtime instance. You can apply multiple templates to the instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files copied to the instance. For additional details and examples about using templates, see Templates Provided by tc Server on page Review the list of instance setup options. 7. Click the Finish button when you are ready to proceed. Note: The configurator does not display a progress bar as it creates the new instance. The configurator displays the new tc Runtime instance in the list. 51

52 About Removing a tc Runtime Instance 1. Click the Start button > All Programs > Pivotal > Pivotal tc Server Configurator. The application opens and displays the list of existing tc Runtime instances. 2. Select the instance that you want to remove. 3. Click the Remove button. The configurator stops the instance Windows service, if started, and removes the instance from your hard drive. Starting and Stopping tc Runtime Instances Manually 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 Using tcruntimectl.sh By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/pivotal-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /opt/pivotal, 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/pivotal and created a new tc Runtime instance called myserver in the /var/opt/pivotal/pivotal-tc-server-standard directory: prompt$ cd /var/opt/pivotal/pivotal-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. 4. Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop command: prompt$./tcruntime-ctl.sh stop 52

53 About 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, tcserver 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/pivotal/pivotal-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. 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. 2. Install the init.d.sh script in the /etc/init.d directory using a command like the following: 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/pivotal/pivotaltc-server-standard directory, enter this command: prompt# ln -s /var/opt/pivotal/pivotal-tc-server-standard/myinstance/bin/ init.d.sh \ /etc/init.d/myinstance 53

54 About 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 8: init.d Commands for tc Runtime Instances Command start stop restart status Description Starts the Instance Shuts down the instance Stops and starts the instance 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\pivotal-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as \opt\pivotal 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 user who 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. 3. 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\pivotal and created a new tc Runtime instance called myserver in the \var\opt\pivotal\pivotal-tc-server-standard directory: prompt> cd \var\opt\pivotal\pivotal-tc-server-standard\myserver\bin 4. Install the tc Runtime instance as a Windows service: 54

55 About 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 Pivotal tc Runtime instance - tcserver-c-var-opt-pivotal-pivotaltc-server-standard-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 Pivotal tc Runtime instance - unique-name, where unique-name 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 Pivotal recommends that you always install the tc Runtime instance as a Windows service and stop and start it using the Services console, you can also stop and start the tc Runtime instance manually. See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script. Windows Java Service Wrapper On Windows, tc Runtime uses a Java Service Wrapper from Tanuki Software to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user logouts under Windows, service dependencies, and the ability to run services which interact with the desktop. The wrapper is configured using the CATALINA_BASE\conf\wrapper.conf file, where CATALINA_BASE is the top-level directory of the tc Runtime instance, such as \var\opt\pivotal \pivotal-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] 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/pivotal-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/pivotal/pivotal-tc-server-standard/myserver/bin prompt$./tcruntime-ctl.sh start 55

56 About 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 -i option: prompt$ cd /opt/pivotal/pivotal-tc-server-standard prompt$./tcruntime-ctl.sh myserver start -i /var/opt/pivotal/pivotal-tcserver-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 9: Commands of the tcruntime-ctl Script Command Description Platform install run-as-user uninstall start Installs the tc Runtime instance as a Windows service. You then start and stop the service using the Windows Service console. The optional run-as-user parameter specifies the user account that you want the tc Runtime service to actually run as when you start the service using the Windows Service console; if you do not specify this parameter, then the user account that initially installed it is used. You can specify only user accounts that have their Logon as Service right set to run a Windows service. See Setting the Logon-As- Service Right for a Windows User. When you run this command and explicitly specify a runas-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. Uninstalls the tc Runtime instance from the Windows Service. Starts the tc Runtime instance as a daemon process. On Windows, you must have previously installed the tc Runtime instance as a Windows service to be able to start it using the tcruntime-ctl.bat start command; see the documentation on the tcruntime-ctl.bat install command in this table for more information. Windows only Windows only Unix and Windows 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. 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 tcruntimectl.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 Unix and Windows 56

57 About Command Description Platform 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 run Starts the tc Runtime instance as a foreground process. Unix and Windows batch stop timeout status verbose-status 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. 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. 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 Reports the status of a tc Runtime instance, such as whether it is running or stopped, as well as useful information such as the tc Runtime version, the instance name, and the instance directory. Reports the same status information as the status command as well as additional information, such as the directory from which the tc Runtime instance gets its binary files, the version of the tcruntime scripts, and so on. Windows only Unix and Windows Unix and Windows 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 10: 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 tcruntimectl.sh bat script. -i tcruntimedir or -n tcruntimedir Replace instancedir with the full pathname of the parent of the tc Runtime instance directory. Use this option if the tc Runtime 57

58 About Option Description 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/pivotal/pivotal-tc-server-standard/ myserver, then you would specify /var/opt/pivotal/pivotaltc-server-standard for this option. The default value of this option is the current working directory. This option was added in tc Server 2.9.1, to be consistent with the -i option used with the tcruntime-instance.sh/bat script to specify an instance directory. The behavior of the -i option is identical to that of the -i option, which, for backward compatibility, is still supported. The following example shows how to stop the tc Runtime instance called myserver, located in the /var/ opt/pivotal/pivotal-tc-server-standard directory, after waiting for up to 60 seconds: prompt$ cd /var/opt/pivotal/pivotal-tc-server-standard/myserver/bin prompt$./tcruntime-ctl.sh stop 60 In the following example, use of the -i option indicates that the tc Runtime instance called myotherinstance has an instance directory of /var/opt/pivotal/pivotal-tc-serverstandard/myotherinstance. The example shows how to use the tcruntime-ctl script located in the main tc Server installation directory. prompt$ cd /opt/pivotal/pivotal-tc-server-standard prompt$./tcruntime-ctl.sh myotherinstance stop 60 -i /var/opt/pivotal/ pivotal-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: 1. From the Windows Start menu, open the Control Panel. 2. Open Administrative Tools. 3. Open the Local Security Policy tool. 4. Expand the Local Policies settings. 5. Click the User Rights Assignment. 6. On the right side, double-click on the Log on as a service policy. 7. Click on the Add User Or Group button and enter the user account name using the wizard. The Local Security Policy tool does not appear to be available on Home versions of Windows 2000 and XP. It is thus not possible to run the tc Runtime service as a specific account under those versions of Windows. 58

59 About Deploy Applications to tc Runtime Instances 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-gui role (tc Runtime 7.0 or tc Runtime 8.0). An entry for the manager-gui role for tc Runtime 7 or tc Runtime 8 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 tc Runtime 7 or tc Runtime 8 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. 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. 59

60 About Deploying Multiple Versions of the Same Application You can deploy multiple instances of the same web application to a tc Server instance. New sessions are served by the most recently deployed revision of the application. This allows you to upgrade an application without interruption of service. If you deploy an application statically or with Tomcat Manager, you must include a revision indicator string in the.war file name prefix in the /webapps directory. The revision indicator distinguishes amont multiple instances. You must conform to the following naming convention. Starting with the second instance, indicate the version as a 6 character numeric value, prepended by two hash marks, increasing the value for each revision. For instance: test## war test## war test## war Users continue to use the same URL to access the application. They do not include the revision number. New sessions use the highest revision deployed. Existing sessions continue to use the revision that is already managing their session. If tc Runtime cannot locate the session in the SessionManager of an earlier revision, the newest revision is used. When all sessions using an earlier revision of an application have ended, you can undeploy it. Embed tc Server You can create an embedded server application with tc Server. In an embedded server application, the application is deployed and run as a JAR; the JAR file launches a main() method which in turn starts the server and deploys itself on it. This section contains general instructions for embedding tc Server. For a worked example, see github.com/vfabric/tcs-embed-example. Prerequisites Maven The instructions below assume the existence of a Maven project into which you wish to embed tc Server. Procedure 1. Create an account at repository.cloudfoundry.com 2. Configure the repository in your project's pom.xml (in the root of your project directory). <repository> <id>tcserver-embed-release</id> <name>tc Server Embedded Runtime</name> <snapshots> <enabled>true</enabled> <updatepolicy>always</updatepolicy> <checksumpolicy>fail</checksumpolicy> </snapshots> <url> url> </repository> 3. Configure dependencies in your project's pom.xml file. See Example pom.xml below. 4. Configure credentials for accessing the tcruntime-release package at build-time, as a server stanza in the Maven settings file (.m2/settings.xml). 60

61 About <settings> <servers>... <server> <id>tcserver-embed-release</id> <username>username</username> <password>decryptedpassword</password> </server>... </servers> </settings> 5. Run the following command to build the application with embedded tc Server and install it in your local Maven repository (.m2), located in your home directory. mvn clean compile assembly:single 6. Start the application with a command like this: java -jar target/example snapshot-jar-with-dependencies.jar Embedded Jars Table 11: tc Server Embedded Jars Group Id Artifact Id Description com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.embed.core Contains all of the core jars for tc Server embedded: catalina.jar, tomcat-coyote.jar,annotationsapi.jar, tomcat-api.jar, tomcatutil.jar, servlet-api.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.embed.jasper Contains all of the JSP classes: jsp-api.jar, jasper-el.jar, jasper.jar, el-api.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.embed.logging.juli Contains the Juli classes: tomcat-juli.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.embed.logging.log4j Contains the log4j classes: log4j.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.embed.cluster Contains classes for clustering: catalina-ha.jar, catalina-tribes.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.dbcp Contains classes for DBCP: tomcat-dbcp.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.apache.tomcat.jdbc Contains classes for Tomcat JDBC: tomcat-jdbc.jar com.springsource.vfabric.tcruntime.embed com.springsource.org.eclipse.jdt.compiler Contains classes for Eclipse compiler: ecj-<version>.jar com.springsource.vfabric.tcruntime.embed com.springsource.tcserver Contains the tc Server classes: tcserver.jar Example pom.xml <project xmlns=" xmlns:xsi=" xsi:schemalocation=" maven.apache.org/xsd/maven xsd"> 61

62 About <modelversion>4.0.0</modelversion> <groupid>com.springsource.tcruntime.embeddedexample</groupid> <artifactid>example</artifactid> <version>0.0.2-snapshot</version> <packaging>jar</packaging> <name>example</name> <url> <properties> <project.build.sourceencoding>utf-8</project.build.sourceencoding> </properties> <build> <plugins> <plugin> <artifactid>maven-assembly-plugin</artifactid> <configuration> <archive> <manifest> <mainclass>com.springsource.tcruntime.embeddedexample.example.app</ mainclass> </manifest> </archive> <descriptorrefs> <descriptorref>jar-with-dependencies</descriptorref> </descriptorrefs> </configuration> <executions> <execution> <id>make-assembly</id> <!-- this is used for inheritance merges --> <phase>package</phase> <!-- bind to the packaging phase --> <goals> <goal>single</goal> </goals> </execution> </executions> </plugin> </plugins> </build> <repositories> <repository> <id>tcserver-embed-release</id> <name>tc Server Embedded Runtime</name> <snapshots> <enabled>true</enabled> <updatepolicy>always</updatepolicy> <checksumpolicy>fail</checksumpolicy> </snapshots> <url> url> </repository> </repositories> <dependencies> <dependency> <groupid>com.springsource.vfabric.tcruntime.embed</groupid> <artifactid>com.springsource.org.apache.tomcat.embed.core</artifactid> <version> b.release</version> </dependency> <dependency> <groupid>com.springsource.vfabric.tcruntime.embed</groupid> <artifactid>com.springsource.org.apache.tomcat.embed.logging.juli</ artifactid> 62

63 About <version> b.release</version> </dependency> <dependency> <groupid>com.springsource.vfabric.tcruntime.embed</groupid> <artifactid>com.springsource.org.apache.tomcat.embed.logging.log4j</ artifactid> <version> b.release</version> </dependency> <dependency> <groupid>com.springsource.vfabric.tcruntime.embed</groupid> <artifactid>com.springsource.org.apache.tomcat.embed.jasper</ artifactid> <version> b.release</version> </dependency> <dependency> <groupid>com.springsource.vfabric.tcruntime.embed</groupid> <artifactid>com.springsource.tcserver</artifactid> <version>2.9.1.release</version> </dependency> <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>3.8.1</version> <scope>test</scope> </dependency> </dependencies> </project> Security Information Pivotal is committed to providing products and solutions that allow you to assess the security of your information, secure your information infrastructure, protect your sensitive information, and manage security information and events to assure effectiveness and regulatory compliance. As part of this commitment, the following Pivotal tc Server-specific security information is provided to help you secure your environment: External Ports Resources That Must Be Protected Log File Locations User Accounts Created at Installation Obtaining and Installing Latest Version of Product External Interfaces, Ports, and Services A tc Runtime instance uses TCP/IP ports to receive incoming requests and send outgoing responses. Different protocols (such as HTTP/S, JMX, and AJP) listen on different ports. If you create a tc Runtime instance using all default values, then the default TCP/IP ports for the various protocols are as follows: HTTP: 8080 HTTPS: 8443 JMX: 6969 AJP: 8009 You can change the TCP/IP listen ports for a particular tc Runtime instance by updating the INSTANCE- DIR/conf/catalina.properties file, where INSTANCE-DIR refers to the directory in which the tc Runtime instance is located, such as /var/opt/pivotal/pivotal-tc-server-standard/ myserver. The following snippet of catalina.properties shows how to change the HTTP, HTTPS, and JMX ports to 8181, 8553, and 7979, respectively: 63

64 About... bio.http.port=8181 bio.https.port=8553 base.jmx.port=7979 Pivotal tc Server does not have any external interfaces or services that need to be enabled or opened. Resources That Must Be Protected The following tc Server configuration files should be readable only by the dedicated tc Server user who runs the tc Runtime instance: server.xml context.xml web.xml catalina.properties jmxremote.password keystore-name.keystore (Instances configured with the BIO or NIO Connector) cert-name.cer (Instances configured with the APR Connector) key-name.key (Instances configured with the APR Connector) These configuration files are specific to a tc Runtime instance and are stored in the INSTANCE-DIR/ conf directory, where INSTANCE-DIR refers to the directory in which the tc Runtime instance is located, such as /var/opt/pivotal/pivotal-tc-server-standard/myserver. Log File Locations The default log files for a tc Runtime instance are as follows: catalina.out: Contains System.out and System.err messages. catalina.date.log: Contains log messages from the Catalina service. localhost.date.log: Contains log messages from the localhost engine of the Catalina service. localhost_access_log.date.txt: Contains information about access requests. These log files are specific to a tc Runtime instance and are stored by default in the INSTANCE-DIR/ logs directory, where INSTANCE-DIR refers to the directory in which the tc Runtime instance is located, such as /var/opt/pivotal/pivotal-tc-server-standard/myserver. These log files should be readable and writable only by the dedicated tc Server user who runs the tc Runtime instance. User Accounts Created at Installation If you install Pivotal tc Server on Red Hat Enterprise Linux (RHEL) using the RPM or install on Ubuntu using a Debian pacakge, then a user with the following characteristics is automatically created: ID: tcserver Group: pivotal Non-interactive, which means that you cannot directly log in to the RHEL computer as this user. Rather, you must log in as root or user with appropriate sudo privileges and su - tcserver. When installing from RPM on RHEL or from a Debian package on Ubuntu, the tc Server installation directory will be owned by the root user, with group vfabric. The tcserver user will have permission to execute appropriate scripts, such as tcruntime-instance.sh and tcruntime-ctl.sh. You should create tc Runtime instances as the tcserver user, and stop and start them as this user. 64

65 About When installing tc Server on Windows or from a *.zip or *.tar file, a user account is not automatically created for you. Rather, you must create a dedicated tc Server user account whose only purpose is to run tc Runtime instances. Additionally: This user should be the only user who has the permission to start and stop the tc Runtime instance, and should have no other permissions. It should not be possible to logon to the computer directly as this dedicated tc Server user. tc Server configuration files should be readable only by this dedicated tc Server user. tc Server log files should be readable and writable only by this dedicated tc Server user. Obtaining and Installing Security Updates Pivotal tc Server is a Web application server based on open-source Apache Tomcat. A particular version of tc Server includes particular versions of Apache Tomcat, such as tomcat a.release or tomcat a.release. New versions of tc Servers typically include updated versions of Apache Tomcat, some of which might fix important security vulnerabilities. To install these security updates, you install the new version of tc Server and then upgrade your existing instances. To download the latest *.zip or *.tar distributions of the Pivotal tc Server, go to the Pivotal Download Center. From the Pivotal tc Server product page, click Downloads. When using RPMs on RHEL, use the yum upgrade command to upgrade to the latest Pivotal tc Server version. When using Debian packages on Ubuntu, use the apt-get upgrade command to upgrade. See Upgrade and Migration Guide for details. Upgrade and Migration Guide Several upgrade procedures are supported for this release of Pivotal tc Server. Subtopics Upgrade Instances with Later tc Runtime Binary Upgrade an Instance in a New tc Server Directory Upgrade an Instance in the Existing tc Server Directory Run an ERS Tomcat Instance on tc Server Migrate an ERS Tomcat Instance to tc Server Upgrade an Instance with a Later tc Runtime Binary This section has instructions for upgrading tc Server instances to a new version of the tc Runtime. Note: If you want to upgrade to the latest tc Server package, one of the two sections: Upgrade an Instance in a New tc Server Directory on page 66 Upgrade an Instance in the Existing tc Server Directory on page 67 For example, suppose that your tc Server release came bundled with tomcat a.release. Later, you could decide to upgrade to the tomcat a.release (or another version) when it is released. The instructions in this section enable you to stay current with new tc Runtime releases, taking advantage of the latest features, security vulnerability fixes, and bug fixes. Before You Start Be sure to stop a tc Server instance before you upgrade the tc runtime version. For instructions, see Starting and Stopping tc Runtime Instances. 65

66 About Procedure 1. Change directory to the tc Server installation directory. For example: prompt$ cd /opt/pivotal/pivotal-tc-server-standard release 2. Use the --list option to view a list of available runtimes to install. The command generally requires a few seconds to return the list.. For example: prompt$./tcruntime-admin.sh get-runtime --list Retrieving Available Runtimes (this may take a moment) Available Runtimes: A.RELEASE A.RELEASE Runtimes are specified by version, such as A.RELEASE. An asterisk (*) indicates that the runtime version is currently installed. 3. Use the --version option to download and install a specific runtime version. For example: prompt$./tcruntime-admin.sh get-runtime --version A.RELEASE Downloading A.RELEASE Expanded A.RELEASE If the specified version is already installed, then the command returns a message similar to the following: prompt$./tcruntime-admin.sh get-runtime --version A.RELEASE Runtime version A.RELEASE has been detected as already being installed. Upgrade an Instance in a New tc Server Directory This section has instructions for upgrading tc Server instances to a new version of tc Server. Run the tcruntime-instance.sh upgrade or (tcruntime-instance.bat upgrade) command to upgrade an existing tc Server instance to a new version of tc Server. The upgrade command migrates configuration information and applications from an existing instance to the new one. The command takes this form: tcruntime-instance.sh -v tcruntimeversion -i PathToNewInstanceDirectory PathToOldInstance where: tcruntimeversion is the Tomcat binary that you want the new instance to use, for example, B.RELEASE. Note: The tc Runtime binary must exist in the new tc Server installation directory. If you want to use a binary that exists in your previous tc Server installation, but not the new one, you must copy it into the new tc Server installation directory. If you do not use the -v option to specify a binary, the upgrade assumes you do not want to upgrade the binary and tries to create the new instance with the same binary. If the older instance uses a version of Tomcat that does not exist in the new version of tc Server, you must copy it from the older tc Server installation to the new one, or the upgrade will fail. PathToNewInstanceDirectory specifies the directory in which you want the upgraded instance to be created. 66

67 About Note: If you do not use the -i option specify a directory, the instance will be created in the current working directory. If you specify the directory where the old instance runs, that instance will be upgraded in place. PathToOldInstance points to the instance that you wish to upgrade. Before You Start Be sure to stop a tc Server instance before you upgrade. For instructions, see Starting and Stopping tc Runtime Instances. Procedure The example commands in the instructions below assume you are upgrading a tc Server instance to Install the new version of tc Server in a new installation directory, as described in Installing Pivotal tc Server. For example, install tc Server in /opt/pivotal/pivotal-tc-serverstandard release. 2. If the directory where you want the upgraded server instance to be installed does not exist, create it. 3. Change directory to new TCS installation directory. For example: prompt$ cd /opt/pivotal/pivotal-tc-server-standard release 4. Run the upgrade command. For example: prompt$ tcruntime-instance.sh upgrade -i../tcs instances - v A.RELEASE../tcs instances/myserver1 The command above creates an upgraded version of the "myserver1" instance in the /tcs instances directory. Upgrade an Instance in the Existing tc Server Directory RHEL: Upgrade Using the Pivotal RPM Repository Pivotal tc Server provides RPMs in Pivotal repositories from which you can install on an RHEL computer or virtual machine. If you originally installed tc Server on the RHEL computer using yum install, then you use yum upgrade to upgrade the installation to the latest version. The yum upgrade process: Installs the latest tc Runtime versions in the /opt/pivotal/pivotal-tc-server-standard directory. The old tc Runtime versions associated with the previous version of tc Server are preserved. Copies the new versions of the tc Server commands and templates to the /opt/pivotal/pivotaltc-server-standard directory. Prerequisites Stop all running tc Runtime instances in the installation that you are upgrading. See Unix: Starting and Stopping tc Runtime Instances Interactively. If necessary, install the Pivotal repository RPM that contains the version of Pivotal tc Server to which you are upgrading. Procedure 1. From the RHEL computer on which you will upgrade Pivotal tc Server, log in as the root user. 67

68 About 2. Execute the following yum command: prompt# yum upgrade pivotal-tc-server-standard The yum command begins the upgrade process, resolves dependencies, and displays the packages it plans to upgrade. 3. Enter y at the prompt to begin the actual upgrade. When the upgrade process finishes, you will see a Complete! message at the end. Check the output of the command to ensure that the upgrade was successful. 4. For each tc Runtime instance that you created in the previous tc Server installation that you want to upgrade, follow these steps: a. If necessary, become the user that created the instances you want to upgrade, such as tcserver: prompt# su - tcserver b. Change to the directory in which the instance is located. For example: prompt$ cd /var/opt/pivotal/pivotal-tc-server-standard c. Execute the tcruntime-instance upgrade command. Specify the name of the tc Runtime instance you are upgrading and use the -v option to specify the new tc Runtime version that the upgraded instance will start to use. For example, if your tc Runtime instance is called myserver: prompt$ /opt/pivotal/pivotal-tc-server-standard/tcruntime-instance.sh upgrade -v A.RELEASE myserver When you start the upgraded tc Runtime instance, it will use the A.RELEASE tc Runtime. Important: If you are upgrading a 2.6.X tc Runtime instance, you must now start and stop the upgraded instance as the tcserver non-interactive user, rather than the tc-server user that was automatically installed in tc Server 2.6. Ubuntu: Upgrade Using the Pivotal Debian Package Repository Pivotal tc Server provides Debian packages in a repository from which you could install on an Ubuntu computer. If you originally installed tc Server on the Ubuntu computer using apt-get install, then you use apt-get install again to upgrade the installation to the latest version. The apt-get upgrade process: Installs the latest tc Runtime versions in the /opt/pivotal/pivotal-tc-server-standard directory. The old tc Runtime versions associated with the previous version of tc Server are preserved. Copies the new versions of the tc Server commands and templates to the /opt/pivotal/pivotaltc-server-standard directory. Prerequisites Stop all running tc Runtime instances in the installation that you are upgrading. See Unix: Starting and Stopping tc Runtime Instances Interactively. Procedure 1. From the Ubuntu computer on which you will upgrade Pivotal tc Server, log in as the root user or as an unprivileged user who has sudo privileges. 2. Execute the apt-get update command so your computer is synchronized with recent changes to the Pivotal Debian package repository: prompt# apt-get update 68

69 About If necessary, use sudo to run the preceding command if you are not logged in as the root user: prompt$ sudo apt-get update 3. Upgrade tc Server using the apt-get install command: prompt# apt-get install pivotal-tc-server-standard The apt-get command begins the upgrade process, resolves dependencies, and displays the packages it plans to upgrade. Enter y at the prompt to begin the actual upgrade. 4. For each tc Runtime instance that you created in the previous tc Server installation that you want to upgrade, follow these steps: a. If necessary, become the user that created the instances you want to upgrade, such as tcserver: prompt# su - tcserver b. Change to the directory in which the instance is located. For example: prompt$ cd /var/opt/pivotal/pivotal-tc-server-standard c. Execute the tcruntime-instance upgrade command. Specify the name of the tc Runtime instance you are upgrading and use the -v option to specify the new tc Runtime version that the upgraded instance will start to use. For example, if your tc Runtime instance is called myserver: prompt$ /opt/pivotal/pivotal-tc-server-standard/tcruntime-instance.sh upgrade -v A.RELEASE myserver When you start the upgraded tc Runtime instance, it will use the A.RELEASE tc Runtime. Run an ERS Tomcat Instance on tc Server This section describes how to run an ERS 4.0 server instance on tc Server with the tc Server Tomcat binaries instead of the binaries included in the ERS Tomcat installation. This process minimizes downtime while preserving the server configuration customizations that were made to the ERS instance and allowing you run the Web applications that were deployed to the ERS instance without redeploying them. Example Environment The procedure below assumes the following environment. Replace the paths with ones that reflect your own environment. ERS 4.0 is installed in the /opt/ers40 directory. The ERS instance to be moved is in /opt/ers40/servers/ers-instance. tc Server is installed on the same computer as ERS Tomcat, in /opt/pivotal/pivotal-tcserver-standard release. tc Server instances are located in the /var/opt/pivotal/pivotal-tc-server-standard directory. Procedure 1. Log on to the computer on which ERS Tomcat and tc Server are installed and open a terminal window. 2. Stop the ERS Tomcat instance if it is running. For example: prompt$ cd /opt/ers40/servers/ers-instance/bin prompt$./tomcat_startup.sh stop 69

70 About 3. Copy the directory that contains the ERS Tomcat instance to the directory for tc Server instances. For example: prompt$ cp -r /opt/ers40/servers/ers-instance /var/opt/pivotal/pivotal-tcserver-standard 4. Open the ERS start script, tomcat_startup.sh (now in /var/opt/pivotal/pivotal-tcserver-standard/ers-instance/bin/), in a text editor, and edit the following variables to point to tc Server directories: root_dir: Set to the tc Server installation directory, for example: root_dir=/opt/pivotal/pivotal-tc-server-standard release tomcat_dir: Set to desired Tomcat binaries directory, for example: tomcat_dir=$root_dir/tomcat a-release server_dir: Set to the tc Server instance directory, for example: /var/opt/pivotal/pivotal-tc-server-standard/$server_name This variable value assumes that you are not changing the name of the migrated instance, which is defined by the $server_name variable in the tomcat_startup.sh script. 5. Start the instance using the ERS start script, tomcat_startup.sh, located in the /var/opt/ pivotal/pivotal-tc-server-standard/ers-instance/bin directory. Because you have updated the variable that points to the Tomcat binaries, the instance will now use tc Server A.RELEASE binaries. 6. Invoke the Welcome page and Web applications in a browser using the same URL (host and port) as before you migrated the ERS Tomcat instance. Migrate an ERS Tomcat Instance to tc Server This section provides general guidelines for migrating an ERS Tomcat instance and Web applications running in it to tc Server. Stop the ERS Tomcat instance. Create a new tc Server instance. For basic instructions, see Create and Modify a Runtime Instance When you create a server instance, you can use a tc Server template to ease the configuration process. For information about available templates, see Using the tc Runtime Templates. Replicate the configuration of the ERS instance in the tc Server instance. Compare the contents of the each of the following files in the /conf directory of the ERS instance with the file of the same name in the /conf directory of the tc Server instance. Edit the tc Server version of the configuration file to replicate the settings from the ERS version of the file. server.xml Review the attributes in the tc Server instance's server.xml file that define port usage and validate that the ports assigned are not used by other servers on the platform, especially if the tc Server instance is on the same computer as the ERS instance. catalina.properties catalina.policy tomcat.users context.xml web.xml logging.properties If the ERS instance's /conf directory contains keystore files, or other artifacts you wish to preserve, copy them to the tc Server instance's /conf directory. 70

71 About Copy the.war files from the /webapps directory of the ERS instance to the /webapps directory of the tc Server instance. Start up the tc Server instance. Invoke each application that you deployed to the tc Server instance to make sure you can access it. To troubleshoot problems see the log files in the.logs directory of the tc Server instance. 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 Pivotal 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/ apache-ant 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: medirectory Hierarchy of the HelloWorld Application 71

72 About 4. Create the Hello.java servlet Java source file and put it in the helloworld/src/examples directory. For sample Java code that you can copy and paste into your own Java file and a brief explanation of how to program a simple servlet, see Hello.java. 5. Create the hello.jsp JSP file and put it in the helloworld/web directory. For sample JSP code that you can copy and paste into your own JSP file and a brief explanation of how to program a simple JSP, see hello.jsp. 6. Create the web.xml Web application deployment descriptor and put it in the helloworld/web/web- INF directory. For sample XML that you can copy and paste into your own web.xml file and a brief explanation of the elements, see web.xml. 7. Create the default index.html page and put it in the helloworld/web directory. For a sample HTML file that you can copy and paste into your own file, see index.html. 8. Create the Ant build file (build.xml) that includes targets for compiling and packaging the Web application and put it in the helloworld directory. For a sample Ant build file that you can copy and paste into your own file, see Ant Build File to Compile and Package the Example on page 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/pivotal directory, set the tcserver.home property in the build.xml file to something like the following: <property name="tcserver.home" value="/opt/pivotal/pivotal-tc-serverstandard release/tomcat a.release" /> 10.Right-click the following image and save it with name Pivotal_Logo.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 72

73 About helloworld/src/examples helloworld/src/examples/hello.java helloworld/web helloworld/web/hello.jsp helloworld/web/images helloworld/web/images/pivotal_logo.png helloworld/web/index.html helloworld/web/web-inf helloworld/web/web-inf/web.xml 11.Compile and package the HelloWorld Web application by opening a command window, changing to the helloworld directory, and executing the following command: prompt> ant all This ant command creates a deployable WAR file of the HelloWorld application called hello.war in the helloworld/dist directory. You will see the following output from the ant command if it completes successfully: Buildfile: build.xml clean: prepare: [mkdir] Created dir: /home/samples/helloworld/dist [mkdir] Created dir: /home/samples/helloworld/work/web-inf/classes [copy] Copying 4 files to /home/samples/helloworld/work compile: [javac] Compiling 1 source file to /home/samples/helloworld/work/web- INF/classes dist: [jar] Building jar: /home/samples/helloworld/dist/hello.war all: BUILD SUCCESSFUL Total time: 2 seconds 12.Start a tc Runtime instance. See Starting and Stopping tc Runtime Instances. 13.Deploy the Web application JAR file to the tc Runtime instance. See Deploying Applications to tc Runtime Instances. 14.Invoke the HelloWorld Web application in your browser: 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. 73

74 About package examples; import java.io.ioexception; import java.io.printwriter; import javax.servlet.servletexception; import javax.servlet.http.httpservlet; import javax.servlet.http.httpservletrequest; import javax.servlet.http.httpservletresponse; /** * Simple Hello servlet. */ public final class Hello extends HttpServlet { /** * Respond to a GET request for the content produced by * this servlet. * 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/pivotal_logo.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: 74

75 About 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. <html> <head> <title>sample Application JSP Page</title> </head> <body bgcolor=white> <table border="0" cellpadding="10"> <tr> <td align=center> <img src="images/pivotal_logo.png"> </td> <td> <h1>sample Application JSP Page</h1> </td> </tr> </table> <br /> <p>this is the output of a JSP page that is part of the HelloWorld application.</p> <%= new String("Hello!") %> </body> </html> Description of the hello.jsp The hello.jsp page is a static HTML page embedded with a JSP command. A JSP command is an XML-like snippet that encapsulates logic that dynamically generates content within the static HTML. JSP commands can include directives, declarations, expressions, actions, and blocks of Java code, all enclosed within angle-brackets, like XML elements. At compile-time, the JSP is converted into a servlet, which is what tc Runtime instance actually 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! 75

76 About 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=" xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <display-name>helloworld Application</display-name> <description> This is a simple web application with a source code organization based on the recommendations of the Application Developer's Guide. </description> <servlet> <servlet-name>helloservlet</servlet-name> <servlet-class>examples.hello</servlet-class> </servlet> <servlet-mapping> <servlet-name>helloservlet</servlet-name> <url-pattern>/hello</url-pattern> </servlet-mapping> </web-app> Description of the web.xml File In the preceding web.xml deployment descriptor file, the <servlet> XML element declares the HelloServlet, the examples.hello Java class implements the servlet, and the <servletmapping> 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/pivotal_logo.png"> </td> 76

77 About <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/pivotal/pivotal-tc-serverstandard release/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"/> <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> 77

78 About <target name="prepare" depends="clean" description="create working dirs and copy static files to work dir"> <mkdir dir="${dist.home}"/> <mkdir dir="${work.home}/web-inf/classes"/> <!-- Copy static HTML and JSP files to work dir --> <copy todir="${work.home}"> <fileset dir="${web.home}"/> </copy> </target> <target name="compile" depends="prepare" description="compile Java sources and copy to WEB-INF/classes dir"> <javac srcdir="${src.home}" destdir="${work.home}/web-inf/classes"> <classpath refid="compile.classpath"/> </javac> <copy todir="${work.home}/web-inf/classes"> <fileset dir="${src.home}" excludes="**/*.java"/> </copy> </target> <target name="dist" depends="compile" description="create WAR file for binary distribution"> <jar jarfile="${dist.home}/${app.name}.war" basedir="${work.home}"/> </target> </project> Description of the build.xml File The Ant build.xml file defines targets for compiling and packaging the HelloWorld Web application. In preparation, the build process first creates an output directory and creates the required directory hierarchy below it for a standard Web application. This includes the WEB-INF directory that will contain the web.xml file. The build process also sets the build's CLASSPATH value to include the required JAR files in the tc Server distribution. The compile target uses the Java compiler to compile the Java servlet file into a class and copies it to the output directory. The package target creates a JAR file of the output directory. Troubleshooting The following sections describe common problems and resolutions. tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite tc Runtime: JVM Performing a Full GC 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. 78

79 About 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 VMware vfabric 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. 79