Creating and Managing tc Runtime Instances

After you install Pivotal tc Server components on all relevant computers, you can perform some or all of the following post-installation tasks, depending on the edition of 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 ().

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.

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.
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.
Open a terminal window (Unix) or Command Prompt (Windows).
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-2.9.0.RELEASE
```
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-tc-server-standard myserver 
```
On Windows:
```
prompt> tcruntime-instance.bat create -i \var\opt\pivotal\pivotal-tc-server-standard 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 version (based on the preferred major version in tc Server) tc Runtime version located in the installation directory, for example 7.0.8.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.

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 nio); this template adds the Non-blocking IO (NIO) 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 1. 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 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 nio-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 `tcruntime-instance.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. 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.property-name=value` . The name of the property depends on the template. For example, the default template (called `nio`) 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: `nio.http.port=9090` `nio.https.port=9191` Then point to this configuration property file using this option: `--properties-file my-property-file` 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.
`--property template-name.property-name=value`	`-p template-name.property-name=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 `nio`). Templates usually have configuration properties. For example, the `nio` 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 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.property-name=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 nio.http.port=9090` 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.
`--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-tc-server-edition/templates` directory, where `edition` refers to the Edition of tc Server you are using (`developer` or `standard`.) Examples of an existing template are `apr-ssl` and `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 Non-blocking IO (NIO) HTTP Connector to the instance. If your templates include a `<Connector>` element, then the script does not add a NIO Connector. For additional details and examples about using templates, see Using the tc Runtime Templates.
`--version version`	`-v version`	Pins the instance to the specified version of tc Runtime, such as `7.0.50.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 `7.0.50.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 (based on the preferred major version in tc Server). The "preferred major" version is the recommended version in tc Server and not necessarily the highest (i.e. tc Runtime 7 or tc Runime 8/8.5). The preferred major for 3.1.x is set to tc Runtime 7. The preferred major version in 3.2.x is tc Runtime 8.5. So, if version is not specified it will pick the highest preferred major version available. For example, if `7.0.37.A.RELEASE`, `7.0.47.B.RELEASE`, `7.0.50.A.RELEASE`, and `8.0.20.B.RELEASE` are all present, and you don't specify this option, then the script automatically chooses `7.0.50.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 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-server-standard --interactive myserver

The following example shows how to pin a new instance to version 7.0.50.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-server-standard  \
    --version 7.0.50.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 nio), rather than use the default value of 8080:

prompt$ ./tcruntime-instance.sh create --property nio.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=7.0.32.B.RELEASE
layout=combined
template.1=nio
template.2=nio-ssl
template.3=async-logger
property.1=nio.http.port=9090
property.2=nio.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.

Assuming the preceding file is called /var/opt/pivotal/properties/my-instance.txt, you would create an instance with these properties using the following command:

prompt$ ./tcruntime-instance.sh create /var/opt/pivotal/properties/my-instance.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 SSL on the instance for added security. SSL is available via the 'nio-ssl' template, so you use the apply-template command of the tcruntime-instance.sh script to apply the new template, nio-ssl, 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 --instance-directory).

Table 2. Options of the apply-template Command
Option (Long Form)	Option (Short Form, if available)	Description
`--help`	`-h`	Outputs usage information for `apply-template.`
`--interactive`	N/A	Tells the script to interactively ask for template-specific configuration properties. For example, use this parameter if you are applying a `nio-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 `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--override-duplicate-template`	N/A	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.property-name=value` . The name of the property depends on the template. For example, the default template (called `nio`) 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: `nio.http.port=9090` `nio.https.port=9191` Then point to this configuration property file using this option: `--properties-file my-property-file` For the list of configuration properties that apply to a particular template, see the `configuration-prompt.properties` file in the `INSTALL_DIR/pivotal-tc-server-edition-release/templates/template-name` directory.
`--property template-name.property-name=value`	`-p template-name.property-name=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 `nio`). Templates usually have configuration properties. For example, the `nio` 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 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.property-name=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 nio.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/pivotal-tc-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-tc-server-edition/templates` directory, where `edition` refers to the Edition of tc Server you are using (`developer` or `standard`.) Examples of an existing template are `apr-ssl` and `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-tc-server-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.

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 7.0.47.A to 7.0.50.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 3. 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 `7.0.50.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 `7.0.50.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 (based on the preferred major version in tc Server). The "preferred major" version is the recommended version in tc Server and not necessarily the highest (i.e. tc Runtime 7 or tc Runime 8/8.5). The preferred major for 3.1.x is set to tc Runtime 7. The preferred major version in 3.2.x is tc Runtime 8.5. So, if version is not specified it will pick the highest preferred major version available. For example, if `7.0.37.A.RELEASE`, `7.0.47.B.RELEASE`, `7.0.50.A.RELEASE`, and `8.0.20.B.RELEASE` are all present, and you don't specify this option, then the start script automatically chooses `7.0.50.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 `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--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 7.0.50.A.RELEASE of tc Runtime; the resulting instance will be pinned to this version:

prompt$ ./tcruntime-instance.sh modify-version --version 7.0.50.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-tc-server-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 modify-version 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:

Install the new tc Server release in a directory alongside the existing tc Server installation.
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 4. 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. 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 `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 `7.0.50.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 7.0.6.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 7.0.57.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 5. Options of the list Command
Option (Long Form)	Option (Short Form)	Description
`--instance-directory instanceDir`	`-i instanceDir`	Replace instanceDir with the full or relative pathname of the directory that contains the tc Runtime instances for which you want a listing. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the `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-server-standard
Listing instances in '/var/opt/pivotal/pivotal-tc-server-standard'
  myInstance Info:
    Instance name:         myInstance
    Runtime version:       7.0.26.A.RELEASE
    tc Runtime Base:       /var/opt/pivotal/pivotal-tc-server-standard/myInstance
    Status:                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 SSL-enabled 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:

nio : Configures a Non-blocking IO (NIO) HTTP Connector.
nio-ssl : Configures a Non-blocking IO (NIO) 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.

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

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.
Open a terminal window (Unix) or Command Prompt (Windows).
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-2.9.0.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.
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 http://host:port , 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:
```
http://localhost:8080 
```
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-server-standard:
```
prompt$ ./tcruntime-ctl.sh myserver start -i /var/opt/pivotal/pivotal-tc-server-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 (based on the preferred major version in tc Server).

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

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

prompt$ ./tcruntime-instance.sh create --version 7.0.50.A.RELEASE \
       -i /var/opt/pivotal/pivotal-tc-server-standard myserver

the myserver instance will always use version 7.0.50.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-server-standard 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 7.0.50.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 7.0.50.A.RELEASE, but the instance finds only the 7.0.37.B.RELEASE and 7.0.42.B.RELEASE versions, then the instance uses the 7.0.42.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 7.0.42.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-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 yourself.

The argument to the --template option of the tcruntime-instance script must exist in 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 edition-version refers to the edition of tc Server you are using (developer or standard) and the version of tc Server. Alternatively, as of tc Server 3.2, the template directory may be specified with --templates-directory.

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 uses the latest installed version of tc Runtime and the value of JAVA_HOME from the environment. The instance is created in the /var/opt/pivotal/pivotal-tc-server-standard/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 Non-blocking IO (NIO) 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.

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 server-fragment.xml or context-fragment.xml, that contain just the additions, deletions, or changes that the script applies to the base instance. When the tcruntime-instance script applies the template after it has created a new base tc Runtime instance, it merges the XML fragment files with the corresponding base conf/server.xml or conf/context.xml file, and copies over any other files, such as JAR files. Depending on the contents of the template directory, the new tc Runtime instance might be quite different from the standard one. For example, the template might modify the standard server.xml file with additional server configuration, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

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 6. Out-of-the-Box Templates Provided by tc Runtime
Template Name	Comparison with Default tc Runtime Instance
base	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.
ajp	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. As of 3.2.20 (tc Runtime 7.0.100+ and 8.5.51+) the attributes and behavior changed for the AJP connector. The use of `requiredSecret` has been deprecated and replaced with `secretRequired` and `secret`. The default listen address has also been changed. The default value for `secretRequired` is `false` in this template. If using on an insecure network please set to `true` and also set `secret`.
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. 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	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. Note: This template is only available for tc Runtime version 7.x
bio	Adds a Blocking IO (BIO) HTTP Connector to the new instance's `server.xml` file. Note: BIO connector was removed in tc Runtime 8.5
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 general information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site. Note: BIO connector was removed in tc Runtime 8.5
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. 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 cluster-node.node.name=my-node`. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcruntime-instance` script will automatically add a Blocking IO (BIO) HTTP Connector in tc Server 3.1.x and will add a Non-blocking IO (NIO) HTTP connector in tc Server 3.2.x. 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 in tc Server 3.1.x and will add a Non-blocking IO (NIO) HTTP connector in tc Server 3.2.x.
gemfire-cs	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. Note: As of 3.2.0, this is now available from the Template Repository
gemfire-p2p	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. Note: As of 3.2.0, this is now available from the Template Repository
insight	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 in tc Server 3.1.x and will add a Non-blocking IO (NIO) HTTP connector in tc Server 3.2.x. 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. Note: As of 3.2.0, this is now available from the Template Repository
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 in tc Server 3.1.x and will add a Non-blocking IO (NIO) HTTP connector in tc Server 3.2.x. 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	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. Note: This template is deprecated and will be removed on December 31, 2020.
redis-session-manager-auth	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. Note: This template is deprecated and will be removed on December 31, 2020.

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 nio-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-nio-ssl.keystore. This keystore contains a self-signed certificate with default values (such as Unknown) for the organization information.
Key alias named tc-server-nio-ssl.
Key password consisting of a random string of characters.
Keystore password that is the same as the key password
HTTPS port of 8443.

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.

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.

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 tcruntime-ctl.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:

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.
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
```
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.
Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop command:
```
prompt$ ./tcruntime-ctl.sh stop
```

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

Unix - Starting tc Runtime Instances Automatically at System Boot Time

When you create a tc Runtime instance on a Unix platform, the tcruntime-instance.sh script creates a boot script, instance-name/bin/init.d.sh, which you can install to start the tc Runtime instance automatically at boot time. Once you install the script, whenever the computer reboots, the tc Runtime instance is automatically started. You can also use the script to control the tc Runtime instance the same way you use other scripts in the /etc/init.d directory.

About Users and Permissions

The scripts in /etc/init.d are owned by root and must be executed by root. When the tc Runtime init.d script executes, it uses /bin/su to execute the tc Runtime instance as another user, tc-server by default. This user account must exist and have permission to read and write all files in the CATALINA_HOME directory.

To ensure that file permissions are correct, you should either create the tc Runtime instance while logged in as the user you want to run the instance, or create the instance and then chown the CATALINA_HOME directory and all of its files and subdirectories to the user you want to run the instance.

Specify the runtime user on the tcruntime-instance.sh create command line when you create the instance by including --property base.runtime.user=run-time-user in the command, as shown in this example:

prompt$ ./tcruntime-instance.sh create --property base.runtime.user=tcserver \
    -i /var/opt/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

In a Unix terminal window, use the su command to become root, if necessary:
```
prompt$ su
Password:
```
Enter the root password at the prompt.
Install the init.d.sh script in the /etc/init.d directory using a command like the following:
```
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/pivotal-tc-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
```
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
```
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 7. init.d Commands for tc Runtime Instances

Command	Description
start	Starts the Instance
stop	Shuts down the instance
restart	Stops and starts the instance
status	Displays information about the tc Runtime instance and whether it is running or not running.

You must be root when you execute the command. For example, to restart a tc Runtime instance named MyInstance:

prompt$ sudo /etc/init.d/MyInstance restart

Windows - Starting and Stopping tc Runtime Instances as Windows Services

By default, the tcruntime-instance.bat script creates all tc Runtime instances under the INSTALL_DIR\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:

Login to the computer on which you installed tc Server as the user who will run the tc Runtime instance, such as tcserver.
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.
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
```
Install the tc Runtime instance as a Windows service:
```
prompt> tcruntime-ctl.bat install
```
The command installs the tc Runtime instance as an automatic Windows Service, which means that the tc Runtime instance starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel.

You should see a message indicating a successful installation:

wrapper | Pivotal tc Runtime instance - tcserver-c-var-opt-pivotal-pivotal-tc-server-standard-myserver installed.
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

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-tc-server-standard

It is assumed in the remainder of this section that you are running the command script from the bin directory of the tc Runtime instance.

The following table describes the tcruntime-ctl script commands and supported platforms.

Table 8. Commands of the tcruntime-ctl Script
Command	Description	Platform
install run-as-user	Installs the tc Runtime instance as a Windows service. You then start and stop the service using the Windows Service console. The optional `run-as-user` parameter specifies the user account that you want the tc Runtime service to actually run as when you start the service using the Windows Service console; if you do not specify this parameter, then the user account that initially installed it is used. You can specify only user accounts that have their `Logon as Service` right set to run a Windows service. See Setting the Logon-As- Service Right for a Windows User. When you run this command and explicitly specify a `run-as-user` user, the script asks you for the password of the specified user. tc Runtime still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it fails with a logon error. You must uninstall the service and reinstall it with the correct password.	Windows only
uninstall	Uninstalls the tc Runtime instance from the Windows Service.	Windows only
start	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.	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 `tcruntime-ctl.bat install` command in this table for more information. By default, the `tcruntime-ctl` script (when stopping the tc Runtime instance) waits for up to 60 seconds for the process to exit gracefully. If the server process exits earlier, the script proceeds to restart the server. If the process has not exited by the end of the timeout period, the script forces a termination of the process before restarting the server. Using the optional `timeout` parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds: `prompt$ ./tcruntime-ctl.sh restart 10`	Unix and Windows
run	Starts the tc Runtime instance as a foreground process.	Unix and Windows
batch	Runs the tc Runtime instance using the `catalina.bat` script as a batch job. Specifically, the script starts the tc Runtime instance by running the following command: `%CATALINA_HOME%\bin\catalina.bat run`.	Windows only
stop timeout	Stops a running tc Runtime instance. By default, the `tcruntime-ctl` script waits for up to 60 seconds for the process to exit gracefully; if it has not, then the script forces a termination of the process. 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`	Unix and Windows
status	Reports the status of a tc Runtime instance, such as whether it is running or stopped, as well as useful information such as the tc Runtime version, the instance name, and the instance directory.	Unix and Windows
verbose-status	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.	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 9. Options of the tcruntime-ctl Script
Option	Description
`-d tcRuntimeDir`	Replace tcRuntimeDir with the full pathname of the tc Server installation directory. Use this option if you are running the `tcruntime-ctl.sh\|bat` script from a location other than its default location. The default value of this option is the location of the `tcruntime-ctl.sh\|bat` script.
`-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 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/pivotal-tc-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-server-standard/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:

From the Windows Start menu, open the Control Panel.
Open Administrative Tools.
Open the Local Security Policy tool.
Expand the Local Policies settings.
Click the User Rights Assignment.
On the right side, double-click on the Log on as a service policy.
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.

Deploy Applications to tc Runtime Instances

Deploying Applications Using Tomcat Manager

The tc Server Standard Edition include a template used to install and configure Tomcat Manager and tc Server Developer Edition includes the Tomcat Manager web application. Tomcat Manager is 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

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> 
```
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> 
```
Restart the tc Runtime instance for the changes to take effect.
Invoke Tomcat Manager in your browser using the following URL:
```
http://host:8080/manager/html 
```
where host refers to the computer running the tc Runtime instance.
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.

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##000001.war 
test##000002.war
test##000003.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.

Embedding 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 working example, see Pivotal tc Server Embedded Example.

Prerequisites

Maven 2.2.1
The instructions below assume the existence of a Maven project into which you wish to embed tc Server.

Procedure

Register an account at http://commercial-repo.pivotal.io
Configure the repository in your project's pom.xml (in the root of your project directory).
Configure dependencies in your project's pom.xml file.

See Example pom.xml.
Configure credentials for accessing the tcruntime-release package at build-time, as a server stanza in the Maven settings file (.m2/settings.xml).
Run the build command to assemble the application with embedded tc Server and install it in your local Maven repository (.m2), located in your home directory.
Start the application by invoking the executable jar created from the build.

Embedded Jars

Table 10. tc Server Embedded Jars

Group Id	Artifact Id	Description
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.embed.core`	Contains all of the core jars for tc Server embedded: catalina.jar, tomcat-coyote.jar,annotations-api.jar, tomcat-api.jar, tomcat-util.jar, servlet-api.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.embed.jasper`	Contains all of the JSP classes: jsp-api.jar, jasper-el.jar, jasper.jar, el-api.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.embed.logging.juli`	Contains the Juli logging classes: tomcat-juli.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.embed.logging.log4j`	Contains the log4j logging classes: log4j.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.embed.cluster`	Contains classes for clustering: catalina-ha.jar, catalina-tribes.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.dbcp`	Contains classes for DBCP: tomcat-dbcp.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.apache.tomcat.jdbc`	Contains classes for Tomcat JDBC: tomcat-jdbc.jar
`tcruntime.embed`	`io.pivotal.tcserver.org.eclipse.jdt.compiler`	Contains classes for Eclipse compiler: ecj-<version>.jar
`tcruntime.embed`	`io.pivotal.tcserver`	Contains the tc Server classes: tcServer.jar