Getting Started with tc Server

The tc Server runtime component, known as tc Runtime, offers substantial usability enhancements over the open-source Apache Tomcat server:

Hyperic is a comprehensive enterprise application management tool for managing and monitoring tc Runtime instances, Spring-powered applications, and a variety of non-SpringSource platforms and application servers such as Apache Tomcat. The server instances and applications can be running on multiple computers. Hyperic provides a single console with powerful dashboards through which you can easily check the health of your applications. With Hyperic , you can:

In addition to the preceding tc Runtime-specific Hyperic tasks, you perform the standard tasks :

SpringSource tc Server includes a full set of diagnostic features that makes it easy for you to troubleshoot problems with a tc Runtime instance or the applications that you deploy to tc Runtime instances. These diagnostic features include:

For some diagnostics features, the tc Server HQ plug-in includes one or more preconfigured alerts that make it easy for you to monitor the tc Runtime instance, as well as manage the various thresholds at which an alert is triggered. For additional information about these diagnostic features, and information about managing the associated Hyperic alerts, see tc Server Administration Guide, under Managing tc Runtime-Related Hyperic Alerts.

You can use the command-line interface (CLI) tcsadmin to:

SpringSource tc Runtime and Apache Tomcat share key standard features of application servers.

Because SpringSource tc Runtime is based on Apache Tomcat 6, it provides a powerful yet lightweight platform that is compatible with existing Tomcat-based applications and with Web applications that run on other Java EE application servers such as IBM WebSphere or Oracle WebLogic. Applications can be seamlessly moved from Apache Tomcat to SpringSource tc Runtime to gain the benefits that SpringSource tc Runtime provides beyond the base Apache Tomcat.

SpringSource tc Runtime has a number of advanced configuration features that Apache Tomcat does not.

SpringSource tc Runtime includes advanced, distributed management and monitoring capabilities through a centralized management console called Hyperic user interface.

The tables in this section list the capabilities that SpringSource tc Runtime provides over and above the base Apache Tomcat and also notes the features that Hyperic provides for existing Apache Tomcat environments.

SpringSource tc Runtime provides a wide range of capabilities that enable developers, administrators, and operators to centrally diagnose, measure, and monitor the distributed application infrastructure.

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

SpringSource tc Runtime provides scripting support for administrators and operators who prefer to create and run scripts to handle distributed configuration and deployment steps.

The Developer Edition of tc Server is geared towards the application developer. It contains the tc Runtime, along with utilities that make it easy to create and start tc Runtime instances and a set of templates that make it easy to quickly create specific preconfigured tc Runtime instances, such as cluster-node ready and SSL-enabled.

This edition also includes Spring Insight, an application that provides real-time visibility into the behavior and performance of your user applications. The Developer Edition contains a template called insight that includes the Spring Insight application. You use this template to create new tc Runtime instances that also have Spring Insight. (Developer Edition does not include access to Hyperic Server and Agent.)

The Developer Edition is distributed as either a ZIP or compressed TAR file with the following names:

The Standard Edition of tc Server is geared towards the administrator. Similar to the Developer Edition, the Standard Edition contains the tc Runtime, scripts to easily create and start tc Runtime instances, and templates to quickly create specific types of tc Runtime instances (such as cluster-node ready or SSL-enabled.) This edition does not include Spring Insight, which is a developer tool.

With the Standard Edition, you have access to the vFabric Hyperic management system, which (as of version 4.5) includes the tc Server HQ plugin in the general distribution. Install vFabric Hyperic if you want to use Hyperic to configure and manage the tc Runtime. If you do not want to use Hyperic to manage tc Runtime instances and want to use the tc Runtime on its own, install only the tc Runtime.

The Standard Edition is distributed as either a ZIP or compressed TAR file with the following names:

To download an evaluation of Hyperic, go to the Hyperic download page.

The Spring Edition of tc Server includes the Standard Edition and Hyperic management components, plus production optimizations for Spring-based applications in the form of instrumented JARs for the following Spring technologies: Spring Framework, Spring Security, Spring Web Flow, and Spring Web Services.

The 2.1.2 release of tc Server does not contain any new features with respect to version 2.1.1. See Fixed Issues for the list of issues that were fixed in this maintenance release.

The 2.1.1.SR01 release of tc Server contains no new features or fixed issues since release 2.1.1. The only change is to update the version of Tomcat used by tc Runtime to version 6.0.32.A. This is a security release to pick up changes since version 6.0.29C of Tomcat. See the Apache Tomcat Changelog for a list of the changes to Tomcat.

The 2.1.1 release of tc Server does not contain any new features with respect to version 2.1.0. See Fixed Issues for the list of issues that were fixed in this maintenance release.

The following features are new or changed in tc Server 2.1.0.

SpringSource tc Runtime supports:

SpringSource tc Runtime runs on versions 1.5 and 1.6 of the Java Runtime Environment (JRE.)

The following table lists the supported configurations for running the tc Runtime.

Because you typically install and run the Hyperic Agent on the same computer as the tc Runtime, you should also consult HQ Agent Requirements.

SpringSource recommends that you follow the guidance of your operating system or JVM vendor when deciding which patch levels should be applied to your computer. In general, the latest patch update levels are recommended.

The following tables list specifically tested patch update levels for the latest 2.1.X version of tc Runtime. This table is updated as new configurations are tested.

No editions of tc Server bundle a JDK or JRE. Before you install tc Server, download and install a JDK or JRE on each computer on which you will install the tc Runtime component of tc Server. If you are installing the HQ components, the JDK or JRE requirement depends on whether you install the platform-specific or platform-neutral version; only the latter requires a JDK or JRE because the former bundles one. See Supported Configurations for platform-specific details of the JDK or JRE versions that are supported and have been tested.

For most platforms you can download and install the Sun JDK or JRE, although for IBM computers you might want to install the IBM-specific JDK or JRE. The following links point to download Web sites:

After you install the JDK or JRE, set your JAVA_HOME environment variable to point to your installation and update your PATH environment variable to point to the JAVA_HOME/bin directory.

Windows only. If you are installing the management components of tc Server (HQ Server and Agent), then you must also set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Set HQ_JAVA_HOME as a system environment variable; if you set it as a user environment variable, the HQ Agent aborts on startup.

This section applies only if you are using the Standard or Spring editions of tc Server and you want to also install the HQ Server and Agents management components using the platform-neutral version of the HQ distribution.

The HQ Server uses a database to store its metadata. The platform-neutral version of HQ Server does not, however, bundle a database. This means that if you do not have a database server already installed on either the computer on which you are going to install HQ Server or on an accessible remote computer, then you must download and install one. The platform-specific versions of the HQ distribution bundle a non-production database for you to get started, although it is not recommended that you use this database for production purposes.

Use Oracle 10g/11g, PostgreSQL, or MySQL 5.x with HQ Server. During the installation of HQ Server, you will provide the database URL for JDBC connection and the database username and password.

To set up one of these databases for use with HQ Server, see Set Up Hyperic Database.

This section contains notes about installing tc Server on Unix systems.

prompt$ tar --help

See Using Spring Insight for overview and usage information about Spring Insight as well as information about creating plug-ins that extend Spring Insight.

For general tc Server post-installation tasks discussed in this section, such as creating tc Runtime instances and starting them, see Next Steps.

See Next Steps for links to post-installation procedures.

This section describes how to install one or more instances of tc Runtime and HQ Agent together (also referred to as a managed node), as well as a single HQ Server; assuming the HQ components are version 4.5 or later, both HQ components automatically include the tc Server HQ plug-in.

Read How tc Server and HQ Work Together to understand the various installation scenarios for managed nodes and the HQ Server. Then decide which tc Server components (tc Runtime, HQ Agent, and HQ Server) you are going to install on your computer(s). The typical scenarios are:

The procedure below breaks the steps into those you do on the managed node computer(s) and those you do on the HQ Server computer. If you are installing everything on the same computer, then simply execute all steps on the same computer.

	Note
	If you will be installing tc Runtime instances on multiple computers you must install HQ Agent on each computer.

If you have an existing HQ installation, see Upgrade and Migration Guide for details about upgrading HQ with the tc Server HQ plug-in.

See Next Steps for links to post-installation procedures.

See Overview of tc Server Directories, Variables, and Configuration Files for conceptual information about tc Server directories and configuration files. See Post-Installation Tasks for the list of typical post-installation procedures, such as creating tc Runtime instances, starting the various components of tc Server and getting started with the HQ user interface.

Then try out the tutorials: Tutorial: Using HQ to Configure and Manage tc Runtime Instances and Tutorial: Very Simple Web Application Development.

The following tc Server variables are used:

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:

After you create a new tc Runtime instance, its CATALINA_BASE directory contains the following sub-directories:

You configure a particular tc Runtime instance by changing its configuration files (either by editing the XML file manually or through the HQ user interface); later chapters of this documentation describe how to do this. All the configuration files for a tc Runtime instance are located in its CATALINA_BASE/conf directory. The most important configuration files are as follows:

This section describes the simplest way to create a new tc Runtime instance. For an explanation of the type of instance that the example creates, see the description following the procedure.

When the preceding sample command completes, the new tc Runtime instance is located by default in the INSTALL_DIR/springsource-tc-server-edition/myserver directory (such as /home/tcserver/springsource-tc-server-standard/myserver); you can specify a different instance directory with the --instance-directory directory option. This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance. For example:

prompt> tcruntime-instance.bat create myserver --instance-directory /home/tcserver/instances

In the preceding example, the myserver instance directory will be /home/tcserver/instances/myserver.

By default, the tc Runtime instance uses the JAVA_HOME environment variable for the Java binaries, or the instance uses the java binary that it found in the PATH environment variable when it started. Because the location of the Java binaries has not been explicitly set, the tc Runtime instance is portable; see Creating Portable tc Runtime Instances for more information. You can specify a different JAVA_HOME using the --java-home option.

The ports of the tc Runtime instance are the default values:

Because the preceding sample use of tcruntime-instance.sh|bat did not specify the --version option, the version of the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script uses the highest version of the tc Runtime it can find in the installation directory, for example 6.0.29.A-RELEASE. 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 a configuration property.

The tcruntime-instance.sh|bat command script has four possible commands, used to create or modify a tc Runtime instance, list the existing instances, or display help for the command script. Each command has its own set of options, as described in the tables later in this section. Depending on the command, you must specify the name of a tc Runtime instance. The general syntax for each of the four commands is as follows; click on the link to see the options for that particular command:

tcruntime-instance create instance-name [options]
tcruntime-instance modify-version instance-name [options]
tcruntime-instance list [options]
tcruntime-instance help [command-name]

prompt$ ./tcruntime-instance.sh create myserver --instance-directory /home/tcserver/instances
    --interactive

prompt$ ./tcruntime-instance.sh create myserver --version 6.0.29.A-RELEASE
    --java-home /home/java/jdk1.6.0_12

prompt$ ./tcruntime-instance.sh create myserver --property bio.http.port=9090

prompt$ ./tcruntime-instance.sh modify-version myotherserver --version 6.0.29.A-RELEASE 

prompt$ ./tcruntime-instance.sh modify-version myotherserver 

prompt$ cd /home/tcserver/springsource-tc-server-standard
prompt$ ./tcruntime-instance.sh list

prompt$ ./tcruntime-instance.sh list --instance-directory /home/tcserver/instances 

prompt$ ./tcruntime-instance.sh help

prompt$ ./tcruntime-instance.sh help create

prompt$ ./tcruntime-instance.sh create -h
prompt$ ./tcruntime-instance.sh create --help

Depending on whether you explicitly specify the --version parameter of the tcruntime-instance.sh|bat script when you create an instance, the resulting tc Runtime instance is either pinned or unpinned to a particular version of tc Runtime. Specifically:

To determine the list of available versions, search for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 6.0.29.A-RELEASE.

For example, if you create a new instance using the following command:

prompt$ ./tcruntime-instance.sh create myserver --version 6.0.29.A-RELEASE

the myserver instance will always use version 6.0.29.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 myserver 

the myserver instance always uses the latest version of tc Runtime that is currently installed. Thus if you later install a new version of tc Runtime (which means that there will be a new tomcat-6.0.X.X-X directory alongside the existing ones), and start the unpinned myserver instance using the tcruntime-ctl.sh|bat script, the instance automatically uses the latest tc Runtime version without your having to explicitly do anything.

To determine whether an existing tc Runtime instance is pinned, check for the file INSTANCE-DIR/conf/tomcat.version; if the file exists, then the instance is pinned to the version specified in the file.

To change the version of a pinned instance, use the modify-version command together with --version to specify the new version. For example:

prompt$ ./tcruntime-instance.sh modify-version myserver --version 6.0.26.A-RELEASE

Finally, if you want to convert a currently pinned instance to one that is unpinned, use the modify-version command without --version. For example:

prompt$ ./tcruntime-instance.sh modify-version myserver 

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 /home/tcserver/springsource-tc-server-standard/myServer directory, then its name is myServer.

The HQ user interface also uses this naming convention when first identifying a tc Runtime instance. In particular, the HQ user interface displays an instance with the name platform-resource tc Runtime catalina-base-dir, where platform-resource refers to the computer on which the tc Runtime instance is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames. The HQ user interface uses the full pathname of CATALINA_BASE as the default description of the instance.

This means, however, that if you create two instances whose full pathnames differ, but their main installation directory names are the same, the instances will show up in the HQ user interface with the same names. This makes it difficult to differentiate multiple tc Runtime instances from each other, although you can always look at the description for the full pathname. For example, assume you have two instances in the following directories running on a computer identified as my-desktop in HQ:

Although they are completely different instances, they will both show up in the HQ user interface with the name my-desktop tc Runtime myServer.

For this reason, SpringSource recommends as a best practice that you use unique names for the main installation directory for each tc Runtime instance on the same computer. For example, the following two instances will show up in the HQ user interface with different names:

Templates make it easier for you to automatically configure certain tc Runtime features at the time you create a tc Runtime instance. These features include SSL, clustering, and so on.

You use the --template option to specify a template to the tcruntime-instance script when you create a new tc Runtime instance. You can specify the --template option multiple times if you want to apply multiple templates, such as clustering and SSL.

When you create a tc Runtime instance using tcruntime-instance, the script performs the following high-level steps:

A template is simply a directory under the INSTALL-DIR/templates directory that contains additional or customized tc Runtime instance files. For example, the directory might contain a conf/server-fragment.xml file, which the tcruntime-instance script uses to update the base server.xml file with the relevant feature. The directory might also contain additional JAR files.

An example of creating an instance using the nio-ssl template is as follows:

prompt$ ./tcruntime-instance.sh create myserver --template nio-ssl

To use this feature, the specified template must already exist. You can use one of the out-of-the-box templates.

The files that make up a template reside in a single directory; the name of the template directory is the name of the template. The template files are organized in the standard Tomcat subdirectory hierarchy. For example, configuration files live in the conf subdirectory and JAR files live in the lib subdirectory. The configuration files in the conf template directory are actually just fragments of XML, called server-fragment.xml or context-fragment.xml, that contain just the additions, deletions, or changes that the script applies to the base instance. When the tcruntime-instance script applies the template after it has created a new base tc Runtime instance, it merges the XML fragment files with the corresponding base conf/server.xml or conf/context.xml file, and copies over any other files, such as JARS. Depending on the contents of the template directory, the new tc Runtime instance might be quite different from the standard one. For example, the template might modify the standard server.xml file with additional server configuration, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

The argument to the --template option must be the tc Runtime template directory. The tcruntime-instance script looks for the template directory in the INSTALL_DIR/springsource-tc-server-edition/templates directory, where edition refers to the Edition of tc Server you are using (developer or standard.)

You can specify the --template option multiple times; the tcruntime-instance script applies each template in the order given. First the script copies over any non-configuration files to tha appropriate instance directory, and then the script merges the configuration file fragments with the instance configuration files. You will receive a warning if the creation of the instance copies over files with the same name and directory location from two or more different templates.

The following example shows how to create a new tc Runtime instance called myserver using the nio out-of-the-box template which adds a NIO Connector to the server.xml file:

prompt$ ./tcruntime-instance.sh create myserver --template nio

In the preceding example, because it does not specify the --version or --java-home options, the instance is unpinned, and thus uses the latest installed version of tc Runtime, and the instance uses the value of JAVA_HOME in the environment.

The following example shows how to create an instance that uses two templates:

prompt$ ./tcruntime-instance.sh create myserver --template insight --template jmx-ssl

Note that the insight template is available only in the Developer Edition of tc Server.

SpringSource tc Runtime provides a number of out-of-the-box templates. Most are server configuration related; for example, one template sets up a basic cluster node configuration and another sets up SSL. Some templates are provided only in certain editions of tc Server, such as the insight template in the Developer Edition.

You can download a tc Server template for setting up HTTP session replication using VMware vFabric GemFire, the in-memory distributed data management platform, from the VMware vFabric GemFire section of the VMware Download Center. See Setting Up GemFire HTTP Session Management for tc Server at the GemFire community website for instructions for using the template.

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 myserver-nio --template 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/springsource-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (developer or standard.)

A portable tc Runtime instance is one whose instance directory you can copy to a new directory name, and the instance still starts and works correctly without your having to update the instance configuration files.

To guarantee the portability of a newly-created tc Runtime instance, do not specify any options of tcruntime-instance.sh|bat. Use the INSTANCE-DIR/bin/tcruntime-ctl.sh|bat script to start and stop the instance.

For example, assume you created a tc Runtime instance called myserver in the main tc Server installation directory:

prompt$ cd /home/tcserver/springsource-tc-server-standard
prompt$ ./tcruntime-instance.sh create myserver

Because this instance is completely portable, you can copy the resulting instance directory to another location, and then start and use this new instance as if you had created it with the tcruntime-instance script. For example, assume you want to copy the myserver instance to the /home/tcserver/instances directory and call it myserver-new:

prompt$ cd /home/tcserver/springsource-tc-server-standard
prompt$ cp -r myserver ../instances/myserver-new
prompt$ cd ../instances/myserver-new/bin
prompt$ ./tcruntime-ctl.sh start

Important: Remember that when you copy an instance in this way, the ports that the two tc Runtime instances listen to will be the same. If you want to run both instances on the same computer, update the conf/catalina.properties file of one instance to differentiate the port name.

You can create two flavors of tc Runtime instances, depending on the layout of their files:

By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/springsource-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver, 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:

See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script.

On Unix platforms, the tc Runtime installation includes a command script file called INSTALL_DIR/springsource-tc-server-edition/boot.rc.template, which is a template file that you can use to customize your Unix boot process so that tc Runtime instances start automatically when your computer starts. It is assumed that you already know how to customize the Unix boot process for your particular platform, so this section does not go into detail about where you should put this particular boot file (although typically you rename the file something like boot.rc and put it in the /etc/rc.d directory.) Rather, this section describes the updates you should make to the boot template file to reflect your tc Runtime instance environment. Consult your Unix administration documentation for further details about customizing the boot process.

A one-to-one relationship exists between a boot.rc file and a tc Runtime instance. For example, to start multiple tc Runtime instances automatically on the same Unix computer, you create separate boot.rc files for each tc Runtime instance, modify each of them to reflect the environment of the corresponding tc Runtime instance, and then put each of these files in the appropriate boot directory.

Edit only the top part of the boot.rc.template file that sets the following environment variables:

The following example specifies the tc Runtime home directory as /home/tcserver/springsource-tc-server-standard, the instance directory as the tc Runtime home directory, the instance name as myserver, the JDK location as /home/java/jdk1.6.0_11, and the tomcat user as the starter of tc Runtime process:

TOMCAT_USER=tomcat
TC_SERVER_HOME=/home/tcserver/springsource-tc-server-standard
INSTANCE_BASE=$TC_SERVER_HOME
INSTANCE_NAME=myserver
JAVA_HOME=/home/java/jdk1.6.0_11

Do not modify any part of the boot.rc.template file after the text DO NOT EDIT BEYOND THIS LINE.

By default, the tcruntime-instance.bat script creates all tc Runtime instances under the INSTALL_DIR\springsource-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as c:\home\tcserver 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:

To uninstall the tc Runtime service, execute the following command:

prompt> tcruntime-ctl.bat uninstall

Although SpringSource 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.

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 c:\home\tcserver\springsource-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.

Important: When you start a tc Runtime instance on Windows using the tcruntime-ctl.bat command script, the script might override the following parameters of the wrapper.conf file with instance-specific values:

This means, for example, that although the wrapper.conf file might appear to set the ARCH parameter to win32, the tcruntime-ctl.bat script overrides this generic value with something else (such as winx86_64) if in fact you are running the tc Runtime instance on a 64-bit computer.

For details about the configuration properties, see Configuration Property Overview.

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/springsource-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 /home/tcserver/springsource-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh start

You can accomplish the same thing by running the command from the springsource-tc-server-standard (or springsource-tc-server-developer) directory by specifying the name of the instance:

prompt$ cd /home/tcserver/springsource-tc-server-standard
prompt$ ./tcruntime-ctl.sh myserver start

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.

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.

The following example shows how to stop the tc Runtime instance called myserver after waiting for 60 seconds:

prompt$ cd /home/tcserver/springsource-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh stop 60

In the following example, use of the -n option indicates that the tc Runtime instance called myotherinstance has an instance directory of /home/tcserver/instances/myotherinstance. The example shows how to use the tcruntime-ctl script located in the main tc Server installation directory.

prompt$ cd /home/tcserver/springsource-tc-server-standard
prompt$ ./tcruntime-ctl.sh myotherinstance stop 60 -n /home/tcserver/instances

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:

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.

To start and stop the HQ Server:

See the HQ_SERVER_INSTALL_DIR/logs/server.log for details about the starting or stopping of the HQ Server.

To start and stop the HQ Agent:

See the HQ_AGENT_INSTALL_DIR/log/agent.log for details about the starting or stopping of the HQ Agent.

To start and stop the HQ Server:

See the HQ_SERVER_INSTALL_DIR\logs\server.log for details about the starting or stopping of the HQ Server.

To start and stop the HQ Agent:

See the HQ_AGENT_INSTALL_DIR\log\agent.log for details about the starting or stopping of the HQ Agent.

This topic applies to the Developer Edition of tc Server only.

The Developer Edition of tc Server includes Tomcat Manager, which is a simple 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 configuration of Developer Edition of tc Server does not automatically authorize any user to access Tomcat Manager. The following procedure describes how to authorize a user to access the application, and then how to invoke the Web application in your browser.

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 from which you are running the tc Runtime instance or from the local computer on which you are running your browser. When deploying from the host, you must specify the context path that users use to actually invoke the application.

For detailed information about Tomcat Manager, see Manager App How-To on the Apache Tomcat Web site.

To uninstall the HQ Server component of tc Server:

To uninstall the HQ Agent component of tc Server:

The following procedure describes how to uninstall the tc Runtime and all its associated instances.

Upgrading a 2.0.X tc Server installation to 2.1.X consists of the following subtasks, which are explained in more detail in the next section:

Depending on how you have configured your tc Server installation, you might perform different subtasks on different computers. For example, on the computer on which you have installed the HQ Agent and runtime component (called a managed node), you perform the second and third subtasks. On the computer on which you installed the HQ Server (and nothing else), you perform only the first subtask. The procedure below breaks the steps into those you do on the managed node computer(s) and those you do on the HQ Server computer. If you have previously installed all components on the same computer, then simply execute all steps on the same computer.

Most of the examples in this section use Unix syntax; if you are upgrading on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script. Other changes between the two platforms are called out.

For simplicity, it is assumed in this procedure that your 2.0.X environment results from you following the 2.0 Quick Start instructions, except that the HQ Server is on a computer different from the tc Runtime instances. In particular, this means that:

If your setup is different, such as the various components are installed in different directories, adjust the procedure accordingly.

To upgrade your 2.0.X tc Server installation to 2.1.X, follow these steps:

When you complete this procedure for all components on all computers, you will have successfully upgraded your 2.0.X tc Server installation to 2.1.X.

After you complete HQ upgrade, you must always use the new versions of HQ Server and Agents rather than the old ones. For details about starting and stopping them, see Starting and Stopping the HQ Server and Agents.

When you first connect to the HQ user interface that is using the upgraded HQ Server, the new 4.5 HQ Agent(s) and other resources show up in the Auto-Discovery portlet. You must add them to the Inventory before you can proceed. The 4.5 HQ Server itself now uses a tc Runtime instance internally (called tc Runtime hq-server, which you add to the Inventory along with eveyrthing other new resource. You should, however, not use this tc Runtime instance for your own purposes.

Your existing 2.0.x tc Runtime instances should already be in the HQ Inventory, and you should be able to manage and control them as before. Any previous custom configuration of the isntances should show up intact, as well as all deployed applications. Additionally, all history and management information about the instance, such as control history, historical metric data, and alert settings, will still be available.

If you created a new 2.1 instance, it will show up in the Auto-Discover panel; as soon as you add it to the HQ inventory, you can start monitoring and managing it as usual. Because you migrated the old 2.0.x instance to this new 2.1 instance, you can delete the old 2.0.X tc Runtime instance from the HQ Inventory.

Upgrading a 2.1.X tc Server installation to a later 2.1.X version consists of the following subtasks:

Depending on how you have configured your tc Server installation, you might perform different subtasks on different computers. For example, on the computer on which you have installed the HQ Agent and runtime component (called a managed node), you perform only the Agent and Runtime upgrade. On the computer on which you installed the HQ Server (and nothing else), you perform only the HQ Server upgrade. If you installed all components on the same computer, then simply execute all sub-tasks on the same computer.

Most of the examples in this section use Unix syntax; if you are upgrading on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script. Other changes between the two platforms are called out.

For simplicity, the examples in this procedure assume that you are upgrading a 2.1.0 tc Runtime to version 2.1.1 (unless otherwise noted.) The procedure describes only how to upgrade the tc Runtime and associated instances; for information about upgrading the Hyperic components, see Upgrade HQ Components.

To upgrade your 2.1.X tc Runtime to a later 2.1.X version, follow these steps:

When you complete this procedure, you will have successfully upgraded your existing 2.1.X tc Runtime to a later version of 2.1.

In the preceding code:

For complete documentation about the Java Servlet technology, including API reference documentation, specifications, and tutorials, see Java Servlet Technology.

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 runs at runtime.

The hello.jsp includes the following simple JSP directive:

<%= new String("Hello!") %>

This JSP directive simply prints out a message to the client (browser): Hello!

For complete documentation about JSPs, including specifications, FAQs, and tutorials, see JavaServer Pages Technology.

In the preceding web.xml deployment descriptor file, the <servlet> XML element declares the HelloServlet, the examples.Hello Java class implements the servlet, and the <servlet-mapping> XML element specifies the /hello URL pattern that invokes the servlet in a browser. This URL pattern is used in the index.html file.

The Ant build.xml file defines targets for compiling and packaging the HelloWorld Web application. In preparation, the build process first creates an output directory and creates the required directory hierarchy below it for a standard Web application. This includes the WEB-INF directory that will contain the web.xml file. The build process also sets the build's CLASSPATH value to include the required JAR files in the tc Server distribution.

The compile target simply uses the Java compiler to compile the Java servlet file into a class and copies it to the output directory. The package target creates a JAR file of the output directory.