create Command
Use the create command to create a new tc Runtime instance.
The create command accepts a number of options for customizing the instance. You can specify these options at the command line or list the options in a file and specify the name of the file after the create command.
When you create a new instance, and you do not specify the --template option to apply one or more specific templates, the tcruntime-instance script creates a basic tc Runtime instance that uses the default template (called bio); this template adds the Blocking IO (BIO) HTTP Connector to the
server.xml of the instance. To configure different or additional features using the templates, such as the NIO Connector, clustering, or SSL, use the --template option to specify the appropriate template; you must use the option for each template you want to apply.
Pivotal recommends that you use the --instance-directory option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the appropriate user (such as tcserver) can write to this directory and that the directory already exists.
Examples of creating new tc Runtime instances are shown after the options reference table.
The following table lists options for the create command of tcruntime-instance.sh|bat. When specifying the most common options, you can use either the short form (such as -i) or the long form (such as --instance-directory); less common options support only the long form.
You can also specify these options in a file and pass the name of the file as a parameter to the create command; see the examples.
Table 2: Options of the create Command
Option (Long Form)
Option (Short Form, if
available) Description
--force N/A Forces the script to create a new tc Runtime instance, even if one already exists.
By default the script does not force the creation.
If you specify this parameter and a tc Runtime instance with the name already exists, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. It is assumed in this case that
Option (Long Form)
Option (Short Form, if
available) Description
you do not want to touch the user-specific files, such as Web applications.
To update the tc Runtime version used by an instance, use the modify-version command, not the --force option.
--help -h Outputs usage information about the
create command usage.
--interactive N/A Tells the script to interactively ask for configuration properties. For example, use this parameter if you want to change the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps. Also use this parameter to change the default SSL configuration values when using the -t option to specify an SSL template, such -t bio-ssl.
Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.
--instance-directory
instanceDir -i instanceDir Replace instanceDir with the full or relative pathname of the directory in which you want the new tc Runtime instance to be created.
If you specify a relative directory pathname, the directory is relative to the directory from which you are running the 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.
Option (Long Form)
Option (Short Form, if
available) Description
Warning: Pivotal recommends that you always use the separate layout, which is why it is the default value if you do not specify this option. For additional information, see Differences Between the Separate and Combined Layouts.
--properties-file
file -f file Specifies the name of a properties file that contains configuration properties that you want to apply to the new tc Runtime instance.
When you create the properties file, it should contain one property per line, in the form template-name.property-name=value . The name of the property depends on the template. For example, the default template (called bio) has two configuration properties: http.port and https.port. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the tcruntime-instance script at the command line, rather than the instance taking the default values, create a file such as the following:
bio.http.port=9090 bio.https.port=9191
Then point to this configuration property file using this option:
--properties-file my-property-file
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
Specifies a single configuration property that you want to apply to the new tc Runtime instance.
When you create a tc Runtime instance, the tcruntime-instance script always applies a template, even if it is the default one (called bio). Templates usually have configuration properties. For example, the bio template has two configuration properties: http.port and https.port. Other templates might specify their own
Option (Long Form)
Option (Short Form, if
available) Description
configuration properties. If you want to pass your own values of these properties to the tcruntime-instance script at the command line, rather than the instance taking the default values, use this option to specify the property in the form template-name.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 bio.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.) An example of an existing template is apr-ssl or cluster-node. If you use this option to specify one or more templates that do not add a <Connector>
element to the server.xml configuration file, the tcruntime-instance script automatically adds a Blocking IO (BIO) HTTP Connector to the instance. If your templates include a <Connector>
element, then the script does not add a BIO Connector.
For additional details and examples about using templates, see Using the tc Runtime Templates.
Option (Long Form)
Option (Short Form, if
available) Description
--version version -v version Pins the instance to the specified version of tc Runtime, such as 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. For example, if 7.0.37.A.RELEASE, 7.0.47.B.RELEASE and
7.0.50.A.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 interactively for configuration properties (such as port numbers) and that you want the new tc Runtime instance to be located in the /var/opt/pivotal/
pivotal-tc-server-standard directory:
prompt$ ./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-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 bio), rather than use the default value of 8080:
prompt$ ./tcruntime-instance.sh create --property bio.http.port=9090 \ -i /var/opt/pivotal/pivotal-tc-server-standard myserver
Creating an Instance From a File
You can also specify most of the options in the previous table in a file and pass the file to the create command if you prefer not to specify the commands at the command-line. The following shows an example of such a file:
template.1=bio template.2=bio-ssl template.3=async-logger
property.1=bio.http.port=9090 property.2=bio.https.port=9191
You can specify multiple templates or properties by using the form template.number or property.number . If you include multiple templates, they are applied in the specified order.
Assume that the preceding file is called /var/opt/pivotal/properties/my-instance.txt, then you would create an instance with these properties using the following command:
prompt$ ./tcruntime-instance.sh create /var/opt/pivotal/properties/my-instance.txt